narai-primitives 2.0.0-rc.1

package/dist/connectors/db/lib/plugin_config.js

@@ -0,0 +1,287 @@
+/**
+ * plugin_config.ts — db-agent plugin-level configuration.
+ *
+ * V2.0: configuration is loaded by `@narai/connector-config` from
+ * `~/.connectors/config.yaml` and `./.connectors/config.yaml`. The CLI
+ * builds a `PluginConfig` from the resolved `db` connector's slice. The
+ * `loadPluginConfig({ explicitPath })` API still parses a YAML file
+ * directly when `--config-path` is supplied — it now expects the new
+ * vocab.
+ *
+ * Shape:
+ *   policy:     global default rules, one of allow/present/escalate/deny per op
+ *   servers:    named DB servers, each with a driver + driver-specific fields,
+ *               and optional per-server `policy` override that merges on top
+ *               of the global.
+ *   audit:      optional JSONL audit trail (path + enabled flag)
+ *
+ * Safety floor: `admin` and `privilege` may be downgraded to `present` /
+ * `escalate` / `deny` but never `allow`. Validation fails at config-load.
+ */
+import * as fs from "node:fs";
+import * as yaml from "js-yaml";
+const _ASSERT_POLICYRULES_KEYS = true;
+void _ASSERT_POLICYRULES_KEYS;
+export const DEFAULT_POLICY = {
+    read: "allow",
+    write: "escalate",
+    delete: "present",
+    admin: "present",
+    privilege: "deny",
+    unbounded_select: "escalate",
+};
+const VALID_UNBOUNDED_MODES = new Set([
+    "escalate",
+    "allow",
+]);
+const VALID_RULES = new Set([
+    "allow",
+    "present",
+    "escalate",
+    "deny",
+]);
+function isPlainObject(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        !Array.isArray(v) &&
+        v.constructor === Object);
+}
+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;
+}
+/**
+ * Merge a global + (optional) per-server policy on top of defaults.
+ * Keys absent from the override fall back to `base`.
+ */
+export function mergePolicy(base, override) {
+    if (override === undefined)
+        return { ...base };
+    return {
+        read: override.read ?? base.read,
+        write: override.write ?? base.write,
+        delete: override.delete ?? base.delete,
+        admin: (override.admin ?? base.admin),
+        privilege: (override.privilege ?? base.privilege),
+        unbounded_select: override.unbounded_select ?? base.unbounded_select,
+    };
+}
+function validateRule(field, value, restricted) {
+    if (typeof value !== "string" || !VALID_RULES.has(value)) {
+        throw new Error(`${field}: expected one of [allow, present, escalate, deny], got: ${JSON.stringify(value)}`);
+    }
+    const rule = value;
+    if (restricted && rule === "allow") {
+        throw new Error(`${field}: 'allow' is not permitted (admin and privilege can be at most 'escalate'; safety floor)`);
+    }
+    return rule;
+}
+function validatePolicyObject(path, raw, allowPartial) {
+    if (raw === undefined || raw === null) {
+        if (allowPartial)
+            return {};
+        return { ...DEFAULT_POLICY };
+    }
+    if (!isPlainObject(raw)) {
+        throw new Error(`${path}: expected an object, got: ${typeof raw}`);
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        switch (k) {
+            case "read":
+                out.read = validateRule(`${path}.read`, v, false);
+                break;
+            case "write":
+                out.write = validateRule(`${path}.write`, v, false);
+                break;
+            case "delete":
+                out.delete = validateRule(`${path}.delete`, v, false);
+                break;
+            case "admin":
+                out.admin = validateRule(`${path}.admin`, v, true);
+                break;
+            case "privilege":
+                out.privilege = validateRule(`${path}.privilege`, v, true);
+                break;
+            case "unbounded_select":
+                if (typeof v !== "string" || !VALID_UNBOUNDED_MODES.has(v)) {
+                    throw new Error(`${path}.unbounded_select: expected one of [escalate, allow], got: ${JSON.stringify(v)}`);
+                }
+                out.unbounded_select = v;
+                break;
+            default:
+                throw new Error(`${path}: unknown key '${k}' (expected: read, write, delete, admin, privilege, unbounded_select)`);
+        }
+    }
+    if (allowPartial)
+        return out;
+    return {
+        read: out.read ?? DEFAULT_POLICY.read,
+        write: out.write ?? DEFAULT_POLICY.write,
+        delete: out.delete ?? DEFAULT_POLICY.delete,
+        admin: (out.admin ?? DEFAULT_POLICY.admin),
+        privilege: (out.privilege ?? DEFAULT_POLICY.privilege),
+        unbounded_select: out.unbounded_select ?? DEFAULT_POLICY.unbounded_select,
+    };
+}
+function validateServer(alias, raw) {
+    if (!isPlainObject(raw)) {
+        throw new Error(`servers.${alias}: expected an object, got: ${typeof raw}`);
+    }
+    const driverRaw = raw["driver"];
+    if (typeof driverRaw !== "string" || driverRaw.length === 0) {
+        throw new Error(`servers.${alias}.driver: required string field (e.g. "sqlite", "postgresql", "mongodb", ...)`);
+    }
+    const policyRaw = raw["policy"];
+    const policy = policyRaw === undefined
+        ? undefined
+        : validatePolicyObject(`servers.${alias}.policy`, policyRaw, true);
+    const approvalModeRaw = raw["approval_mode"];
+    if (approvalModeRaw !== undefined &&
+        typeof approvalModeRaw !== "string") {
+        throw new Error(`servers.${alias}.approval_mode: expected string, got: ${typeof approvalModeRaw}`);
+    }
+    const out = { driver: driverRaw };
+    if (policy !== undefined)
+        out.policy = policy;
+    if (typeof approvalModeRaw === "string")
+        out.approval_mode = approvalModeRaw;
+    for (const [k, v] of Object.entries(raw)) {
+        if (k === "driver" || k === "policy" || k === "approval_mode")
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+function validateAudit(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isPlainObject(raw)) {
+        throw new Error(`audit: expected an object, got: ${typeof raw}`);
+    }
+    const enabled = raw["enabled"];
+    const pathVal = raw["path"];
+    if (typeof enabled !== "boolean") {
+        throw new Error(`audit.enabled: expected boolean, got: ${typeof enabled}`);
+    }
+    if (enabled) {
+        if (typeof pathVal !== "string" || pathVal.length === 0) {
+            throw new Error(`audit.path: expected non-empty string when audit.enabled is true`);
+        }
+        return { enabled, path: pathVal };
+    }
+    if (pathVal !== undefined && pathVal !== null) {
+        if (typeof pathVal !== "string" || pathVal.length === 0) {
+            throw new Error(`audit.path: expected non-empty string when present`);
+        }
+        return { enabled, path: pathVal };
+    }
+    return { enabled };
+}
+/**
+ * Validate a raw parsed YAML object against the plugin-config schema.
+ * Throws a descriptive error on any shape or value violation.
+ */
+export function validatePluginConfig(raw) {
+    if (!isPlainObject(raw)) {
+        throw new Error(`plugin config: expected a YAML mapping at root, got: ${typeof raw}`);
+    }
+    const policy = validatePolicyObject("policy", raw["policy"], false);
+    const serversRaw = raw["servers"];
+    if (serversRaw === undefined || serversRaw === null) {
+        throw new Error(`servers: required (at least one named server — keys are aliases)`);
+    }
+    if (!isPlainObject(serversRaw)) {
+        throw new Error(`servers: expected an object, got: ${typeof serversRaw}`);
+    }
+    if (Object.keys(serversRaw).length === 0) {
+        throw new Error(`servers: must contain at least one named server`);
+    }
+    const servers = {};
+    for (const [alias, rawSrv] of Object.entries(serversRaw)) {
+        servers[alias] = validateServer(alias, rawSrv);
+    }
+    const audit = validateAudit(raw["audit"]);
+    const out = { policy, servers };
+    if (audit !== undefined)
+        out.audit = audit;
+    for (const k of Object.keys(raw)) {
+        if (k !== "policy" && k !== "servers" && k !== "audit") {
+            throw new Error(`plugin config: unknown top-level key '${k}' (expected: policy, servers, audit)`);
+        }
+    }
+    return out;
+}
+/**
+ * Parse + validate a plugin config from an explicit YAML file. Returns null
+ * when the file is not plugin-shaped (no `policy:` or `servers:` at the
+ * root) so callers can fall through to legacy parsers.
+ *
+ * V2.0: discovery via `~/.db-agent/` is removed. Standalone CLI runs read
+ * from `~/.connectors/config.yaml` via `@narai/connector-config`. This API
+ * remains for callers that pass `--config-path` directly.
+ */
+export function loadPluginConfig(opts = {}) {
+    if (opts.explicitPath === undefined || opts.explicitPath.length === 0) {
+        return null;
+    }
+    if (!fs.existsSync(opts.explicitPath)) {
+        throw new Error(`Config file not found: ${opts.explicitPath}`);
+    }
+    const parsed = readYaml(opts.explicitPath);
+    if (!isPluginShape(parsed))
+        return null;
+    return validatePluginConfig(parsed);
+}
+function isPluginShape(raw) {
+    return (Object.prototype.hasOwnProperty.call(raw, "policy") ||
+        Object.prototype.hasOwnProperty.call(raw, "servers"));
+}
+/**
+ * Build a `PluginConfig` from a `connector-config`-resolved slice.
+ *
+ * The connector-config lib uses the new vocab natively. Each value in
+ * `slice.policy` is mapped onto our `PolicyRules`; `slice.options.servers`
+ * is validated through the same `validateServer` path so per-server
+ * overrides are still safety-checked.
+ */
+export function pluginConfigFromSlice(slice) {
+    const policy = validatePolicyObject("policy", slice.policy ?? {}, false);
+    const options = slice.options ?? {};
+    const serversRaw = options["servers"];
+    if (serversRaw === undefined || serversRaw === null) {
+        throw new Error(`servers: required (at least one named server — keys are aliases)`);
+    }
+    if (!isPlainObject(serversRaw)) {
+        throw new Error(`servers: expected an object, got: ${typeof serversRaw}`);
+    }
+    if (Object.keys(serversRaw).length === 0) {
+        throw new Error(`servers: must contain at least one named server`);
+    }
+    const servers = {};
+    for (const [alias, rawSrv] of Object.entries(serversRaw)) {
+        servers[alias] = validateServer(alias, rawSrv);
+    }
+    const audit = validateAudit(options["audit"]);
+    const out = { policy, servers };
+    if (audit !== undefined)
+        out.audit = audit;
+    return out;
+}
+// `parseCredentialRef`, `CredentialRef`, and `KNOWN_PROVIDERS` live in
+// `@narai/credential-providers` now.
+//# sourceMappingURL=plugin_config.js.map

package/dist/connectors/db/lib/plugin_config.js.map

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

package/dist/connectors/db/lib/policy.d.ts

@@ -0,0 +1,162 @@
+import type { DatabaseDriver } from "./drivers/base.js";
+import { type PolicyRules } from "./plugin_config.js";
+/** Possible outcomes of a policy check (wire format = lowercase string). */
+export type Decision = "allow" | "deny" | "escalate" | "present_only";
+/** Namespace providing Python-style attribute access (`Decision.ALLOW`). */
+export declare const Decision: {
+    ALLOW: "allow";
+    DENY: "deny";
+    ESCALATE: "escalate";
+    PRESENT_ONLY: "present_only";
+};
+/** Classification of statements by intent (V2.0 vocab). */
+export type OperationType = "read" | "write" | "delete" | "admin" | "privilege";
+/** Namespace mirroring Python's `OperationType.READ` etc. */
+export declare const OperationType: {
+    READ: "read";
+    WRITE: "write";
+    DELETE: "delete";
+    ADMIN: "admin";
+    PRIVILEGE: "privilege";
+};
+/** Discriminated union: `formatted_sql` is REQUIRED only when decision === "present_only". */
+export type PolicyResult = {
+    decision: "allow";
+    reason: string;
+} | {
+    decision: "deny";
+    reason: string;
+} | {
+    decision: "escalate";
+    reason: string;
+} | {
+    decision: "present_only";
+    reason: string;
+    formatted_sql: string;
+};
+/**
+ * Classify a SQL string by its leading keyword.
+ *
+ * Exported so SQL drivers (sqlite, postgres, mysql, mssql) can implement
+ * `DatabaseDriver.classifyOperation` without instantiating a Policy. Throws
+ * `Error("Empty SQL statement")` for empty/whitespace-only input.
+ *
+ * Default-deny: any unknown first-word falls through to `ADMIN` (most
+ * restrictive), matching `policy.py`'s safety-floor intent.
+ */
+export declare function classifySqlKeywords(sql: string): OperationType;
+/**
+ * Classify every statement in a compound SQL string. Comments are stripped,
+ * then the input is split on semicolons (outside quoted literals). Each
+ * non-empty statement is classified via `classifySqlKeywords`. Throws
+ * `"Empty SQL statement"` when the result would be zero statements — same
+ * contract as `classifySqlKeywords` on empty input.
+ *
+ * The CLI pre-check and `Policy.checkQuery` both use this so that a compound
+ * like `SELECT 1; DROP TABLE users;` is classified as [READ, ADMIN] and the
+ * strictest rule (under V2.0 default `admin: present` → present_only) wins.
+ * A compound of all reads classifies as [READ, READ, ...] and the aggregate
+ * decision is allow.
+ */
+export declare function classifyStatements(sql: string): OperationType[];
+export type ApprovalMode = "auto" | "confirm_once" | "confirm_each" | "grant_required";
+/**
+ * Stateful policy engine that gates SQL execution.
+ *
+ * Parameters
+ * ----------
+ * approvalMode : string
+ *     One of: auto, confirm_once, confirm_each, grant_required.
+ */
+export declare class Policy {
+    private readonly _approval_mode;
+    private readonly _rules;
+    private _session_approved;
+    private readonly _grants;
+    private readonly _expired_logged;
+    constructor(approvalMode?: string, rules?: PolicyRules);
+    /** Remove SQL comments from the statement. */
+    static _stripComments(sql: string): string;
+    /** Determine the OperationType of a raw SQL string. */
+    classifySql(sql: string): OperationType;
+    /** Return true if the SELECT appears to lack a bounding clause. */
+    static _isUnboundedSelect(sql: string): boolean;
+    /**
+     * Evaluate whether `sql` should be executed under current policy.
+     *
+     * G-DB-1: when `driver` is supplied, classification is delegated to
+     * `driver.classifyOperation()`. This lets non-relational drivers
+     * (MongoDB, DynamoDB) classify their JSON envelope queries instead of
+     * falling through SQL keyword matching (which would default to ADMIN).
+     *
+     * G-DB-AUDIT: every `deny` decision is emitted as a `policy_deny` event
+     * via `audit.logEvent`. The audit module no-ops when audit is disabled.
+     */
+    checkQuery(sql: string, driver?: DatabaseDriver): PolicyResult;
+    /**
+     * Single-statement decision path. Factored out so compound handling can
+     * call it per sub-statement without emitting audit events (those are
+     * consolidated into one emission after combining). Compatible with the
+     * driver-provided path: when a non-SQL driver supplies its own
+     * `classifyOperation`, the whole query string flows through here.
+     */
+    private _decideOne;
+    /**
+     * Driver-provided path: the caller owns classification (possibly via a
+     * JSON envelope for MongoDB/DynamoDB). Emits the audit event itself since
+     * we're not aggregating across multiple sub-statements here.
+     */
+    private _checkSingleStatement;
+    /** Apply approval-mode logic for READ operations. */
+    private _checkRead;
+    /** Mark the current session as approved (for confirm_once mode). */
+    approveSession(): void;
+    /**
+     * Add a time-limited grant.
+     *
+     * G-DB-AUDIT: emits a `grant_added` event with the grant type and TTL.
+     *
+     * Lifetime scope: grants are in-process only. Expiry is measured with
+     * `performance.now()`, which is reset on every Node process start, so
+     * a new CLI invocation always begins with no active grants — even if
+     * a previous run added one seconds ago. Suitable for the CLI's
+     * single-invocation model; not suitable as a cross-process gate.
+     */
+    addGrant(grantType: string, ttlSeconds?: number): void;
+    /**
+     * Check whether a grant is currently active (not expired).
+     *
+     * G-DB-AUDIT: emits a single `grant_expired` event the first time an
+     * expired grant is observed (subsequent checks are silent so the audit
+     * log isn't spammed by repeated polling).
+     */
+    isGrantActive(grantType: string): boolean;
+}
+/**
+ * Issue a time-limited grant whose TTL derives from an environment's
+ * `grant_duration_hours` field (v2 design §4 default: 8 hours).
+ *
+ * This is the recommended API for prod callers — `addGrant` remains the
+ * low-level primitive (5-minute default, used for short-lived operations
+ * like test scaffolding and administrative confirmations).
+ *
+ * Lifetime scope: grants live in memory only. Because `addGrant` uses
+ * `performance.now()` — a process-relative monotonic clock — a grant
+ * written in one CLI invocation does NOT carry into the next one, even
+ * if `grant_duration_hours=8`. The "8 hour" default means "up to 8
+ * wall-clock hours within a single long-running session," not "8
+ * wall-clock hours across reboots." Persisting grants to disk is out
+ * of scope for v2.
+ */
+export declare function grantFromEnv(policy: Policy, env: {
+    grant_duration_hours?: number;
+}, grantType: string): void;
+/**
+ * Serialize a PolicyResult to JSON.
+ *
+ * Key order: decision, reason, (formatted_sql only when decision ===
+ * "present_only"). V8 preserves string-key insertion order so explicit
+ * construction is sufficient.
+ */
+export declare function policyResultJson(result: PolicyResult): string;
+//# sourceMappingURL=policy.d.ts.map

package/dist/connectors/db/lib/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../src/connectors/db/lib/policy.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtE,4EAA4E;AAC5E,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,cAAc,CAAC;AAEtE,4EAA4E;AAC5E,eAAO,MAAM,QAAQ;;;;;CAKe,CAAC;AAErC,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;AAEhF,6DAA6D;AAC7D,eAAO,MAAM,aAAa;;;;;;CAMe,CAAC;AAE1C,8FAA8F;AAC9F,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,QAAQ,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAmCxE;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAe9D;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE,CAM/D;AAqBD,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,cAAc,GACd,cAAc,GACd,gBAAgB,CAAC;AAMrB;;;;;;;GAOG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAe;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAG9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAc;gBAG5C,YAAY,GAAE,MAAe,EAC7B,KAAK,GAAE,WAA4B;IAiBrC,8CAA8C;IAC9C,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAM1C,uDAAuD;IACvD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAQvC,mEAAmE;IACnE,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAS/C;;;;;;;;;;OAUG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,YAAY;IAwE9D;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAqBlB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAoB7B,qDAAqD;IACrD,OAAO,CAAC,UAAU;IAmDlB,oEAAoE;IACpE,cAAc,IAAI,IAAI;IAItB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,GAAE,MAAY,GAAG,IAAI;IAS3D;;;;;;OAMG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;CAa1C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE;IAAE,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,EACtC,SAAS,EAAE,MAAM,GAChB,IAAI,CAGN;AAqGD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAY7D"}