@qlingzzy/qling 1.0.0

package/dist/git/auto-commit.d.ts

@@ -0,0 +1,28 @@
+export type GitAutoCommitMode = "off" | "on" | "ask";
+export interface AutoCommitInput {
+    workspaceDir: string;
+    filePath: string;
+    toolName: string;
+    mode?: GitAutoCommitMode;
+    /** 可注入以便单测 */
+    runGit?: (args: string[], cwd: string) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    isGitRepo?: (cwd: string) => boolean;
+}
+export interface AutoCommitResult {
+    mode: GitAutoCommitMode;
+    attempted: boolean;
+    committed: boolean;
+    message: string;
+    commitSubject?: string;
+}
+export declare function resolveGitAutoCommitMode(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): GitAutoCommitMode;
+export declare function buildAutoCommitSubject(toolName: string, relPath: string): string;
+/**
+ * 在 write/patch 成功后按策略尝试 git add + commit。
+ * 失败不抛到调用方工具结果（返回 message 由上层附加提示）。
+ */
+export declare function maybeAutoCommitAfterWrite(input: AutoCommitInput): Promise<AutoCommitResult>;
+//# sourceMappingURL=auto-commit.d.ts.map

package/dist/git/auto-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-commit.d.ts","sourceRoot":"","sources":["../../src/git/auto-commit.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,cAAc;IACd,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,iBAAiB,CAKnB;AAmBD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIhF;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyEjG"}

package/dist/git/auto-commit.js

@@ -0,0 +1,112 @@
+// ============================================================
+// 轻灵 - 写工具后的可选 Git 自动提交策略
+// QLING_GIT_AUTO_COMMIT=off|on|ask  （默认 off）
+// ============================================================
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { existsSync } from "fs";
+import { join, relative, resolve } from "path";
+const execFileAsync = promisify(execFile);
+export function resolveGitAutoCommitMode(env = process.env) {
+    const raw = String(env.QLING_GIT_AUTO_COMMIT ?? "off").trim().toLowerCase();
+    if (raw === "on" || raw === "true" || raw === "1" || raw === "yes")
+        return "on";
+    if (raw === "ask" || raw === "prompt")
+        return "ask";
+    return "off";
+}
+function defaultIsGitRepo(cwd) {
+    return existsSync(join(cwd, ".git"));
+}
+async function defaultRunGit(args, cwd) {
+    const res = await execFileAsync("git", args, {
+        cwd,
+        timeout: 15_000,
+        windowsHide: true,
+        maxBuffer: 2 * 1024 * 1024,
+    });
+    return {
+        stdout: String(res.stdout ?? ""),
+        stderr: String(res.stderr ?? ""),
+    };
+}
+export function buildAutoCommitSubject(toolName, relPath) {
+    const safeTool = toolName.replace(/[^\w.-]+/g, "") || "edit";
+    const safePath = relPath.replace(/\\/g, "/");
+    return `qling: ${safeTool} ${safePath}`.slice(0, 200);
+}
+/**
+ * 在 write/patch 成功后按策略尝试 git add + commit。
+ * 失败不抛到调用方工具结果（返回 message 由上层附加提示）。
+ */
+export async function maybeAutoCommitAfterWrite(input) {
+    const mode = input.mode ?? resolveGitAutoCommitMode();
+    const workspaceDir = resolve(input.workspaceDir || process.cwd());
+    const absPath = resolve(input.filePath);
+    let relPath;
+    try {
+        relPath = relative(workspaceDir, absPath).replace(/\\/g, "/") || absPath;
+    }
+    catch {
+        relPath = absPath;
+    }
+    if (mode === "off") {
+        return {
+            mode,
+            attempted: false,
+            committed: false,
+            message: "git auto-commit=off",
+        };
+    }
+    if (mode === "ask") {
+        return {
+            mode,
+            attempted: false,
+            committed: false,
+            message: `git auto-commit=ask：已修改 ${relPath}。确认后可运行 /commit 提交。`,
+        };
+    }
+    // mode === "on"
+    const isGit = (input.isGitRepo ?? defaultIsGitRepo)(workspaceDir);
+    if (!isGit) {
+        return {
+            mode,
+            attempted: false,
+            committed: false,
+            message: `git auto-commit=on 但 ${workspaceDir} 不是 git 仓库，已跳过。`,
+        };
+    }
+    const runGit = input.runGit ?? defaultRunGit;
+    const subject = buildAutoCommitSubject(input.toolName, relPath);
+    try {
+        await runGit(["add", "--", absPath], workspaceDir);
+        const status = await runGit(["status", "--porcelain", "--", absPath], workspaceDir);
+        if (!String(status.stdout || "").trim()) {
+            return {
+                mode,
+                attempted: true,
+                committed: false,
+                message: `git auto-commit: ${relPath} 无待提交变更（可能已被忽略）。`,
+                commitSubject: subject,
+            };
+        }
+        await runGit(["commit", "-m", subject], workspaceDir);
+        return {
+            mode,
+            attempted: true,
+            committed: true,
+            message: `git auto-commit: 已提交「${subject}」`,
+            commitSubject: subject,
+        };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            mode,
+            attempted: true,
+            committed: false,
+            message: `git auto-commit 失败: ${detail}`,
+            commitSubject: subject,
+        };
+    }
+}

package/dist/guard/approval.d.ts

@@ -0,0 +1,16 @@
+import type { ApprovalRequest, ApprovalResponse } from "../channels/types.js";
+export declare class ApprovalGate {
+    private pending;
+    requestApproval(request: ApprovalRequest, channel: {
+        requestApproval: (req: ApprovalRequest) => Promise<ApprovalResponse>;
+    }, timeoutMs?: number): Promise<ApprovalResponse>;
+    getPendingCount(): number;
+    cancelAll(): void;
+}
+export declare class ApprovalRequiredError extends Error {
+    toolCallId: string;
+    toolName: string;
+    reasons: string[];
+    constructor(toolCallId: string, toolName: string, reasons: string[]);
+}
+//# sourceMappingURL=approval.d.ts.map

package/dist/guard/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../src/guard/approval.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE9E,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAMX;IAEE,eAAe,CACnB,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE;QAAE,eAAe,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;KAAE,EACjF,SAAS,GAAE,MAAgB,GAC1B,OAAO,CAAC,gBAAgB,CAAC;IAsC5B,eAAe,IAAI,MAAM;IAIzB,SAAS,IAAI,IAAI;CAWlB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;gBAEN,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE;CAOpE"}

package/dist/guard/approval.js

@@ -0,0 +1,68 @@
+// ============================================================
+// 轻灵 - Approval Gate（审批流）
+// Promise 暂停机制 + 超时自动拒绝
+// ============================================================
+export class ApprovalGate {
+    pending = new Map();
+    async requestApproval(request, channel, timeoutMs = 300_000) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                if (this.pending.has(request.id)) {
+                    this.pending.delete(request.id);
+                    resolve({
+                        requestId: request.id,
+                        decision: "deny",
+                        timestamp: Date.now(),
+                    });
+                    console.error("[Approval] Timeout auto-denied: " + request.id);
+                }
+            }, timeoutMs);
+            this.pending.set(request.id, { resolve, timer });
+            channel.requestApproval(request).then((response) => {
+                const pending = this.pending.get(request.id);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pending.delete(request.id);
+                    resolve(response);
+                }
+            }).catch(() => {
+                const pending = this.pending.get(request.id);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pending.delete(request.id);
+                    resolve({
+                        requestId: request.id,
+                        decision: "deny",
+                        timestamp: Date.now(),
+                    });
+                }
+            });
+        });
+    }
+    getPendingCount() {
+        return this.pending.size;
+    }
+    cancelAll() {
+        for (const [id, { resolve, timer }] of this.pending) {
+            clearTimeout(timer);
+            resolve({
+                requestId: id,
+                decision: "deny",
+                timestamp: Date.now(),
+            });
+        }
+        this.pending.clear();
+    }
+}
+export class ApprovalRequiredError extends Error {
+    toolCallId;
+    toolName;
+    reasons;
+    constructor(toolCallId, toolName, reasons) {
+        super("approval_required");
+        this.name = "ApprovalRequiredError";
+        this.toolCallId = toolCallId;
+        this.toolName = toolName;
+        this.reasons = reasons;
+    }
+}

package/dist/guard/content-filter.d.ts

@@ -0,0 +1,15 @@
+export interface ContentFilterResult {
+    blocked: boolean;
+    reason?: string;
+    matches?: string[];
+}
+export declare function setCustomPatterns(patterns: string[]): void;
+export declare function filterPII(text: string): ContentFilterResult;
+export declare function filterInjection(text: string): ContentFilterResult;
+export declare function filterCustom(text: string): ContentFilterResult;
+export declare function applyContentFilter(text: string, options?: {
+    pii?: boolean;
+    injection?: boolean;
+    custom?: boolean;
+}): ContentFilterResult;
+//# sourceMappingURL=content-filter.d.ts.map

package/dist/guard/content-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-filter.d.ts","sourceRoot":"","sources":["../../src/guard/content-filter.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAmCD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAU1D;AAID,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAY3D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAYjE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAY9D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CACb,GACL,mBAAmB,CAgBrB"}

package/dist/guard/content-filter.js

@@ -0,0 +1,102 @@
+// ============================================================
+// 轻灵 - Guard M2: 内容过滤器
+// PII 检测 + Prompt Injection 扫描
+// ============================================================
+// --- PII Patterns ---
+const PII_PATTERNS = [
+    // 中国手机号（1开头11位）
+    { name: "phone_cn", pattern: /1[3-9]\d{9}/g, mask: "***phone***" },
+    // 中国身份证号（18位）
+    { name: "id_card_cn", pattern: /\d{6}(19|20)\d{9}[0-9Xx]/g, mask: "***id***" },
+    // 邮箱地址
+    { name: "email", pattern: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, mask: "***email***" },
+    // 信用卡号（13-19位数字，可能有空格/横线分隔）
+    { name: "credit_card", pattern: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{1,7}\b/g, mask: "***card***" },
+];
+// --- Prompt Injection Patterns ---
+const INJECTION_PATTERNS = [
+    /ignore\s+(all\s+)?previous\s+instructions/i,
+    /disregard\s+(all\s+)?prior\s+(instructions|prompts)/i,
+    /forget\s+(everything|all)\s+(you|about)/i,
+    /you\s+are\s+now\s+(a|an)\s+/i,
+    /new\s+instructions?:/i,
+    /system\s*:\s*you\s+are/i,
+    /\[INST\]/i,
+    /\[\/INST\]/i,
+    /<\|im_start\|>/i,
+    /<\|im_end\|>/i,
+    /override\s+(safety|security|content)\s+(filter|policy)/i,
+];
+// --- Custom Patterns ---
+let customPatterns = [];
+export function setCustomPatterns(patterns) {
+    customPatterns = patterns
+        .map((p) => {
+        try {
+            return new RegExp(p, "i");
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((p) => p !== null);
+}
+// --- Filter Functions ---
+export function filterPII(text) {
+    const matches = [];
+    for (const { name, pattern } of PII_PATTERNS) {
+        const found = text.match(pattern);
+        if (found) {
+            matches.push(...found.map((m) => name + ": " + m));
+        }
+    }
+    if (matches.length > 0) {
+        return { blocked: true, reason: "PII detected", matches };
+    }
+    return { blocked: false };
+}
+export function filterInjection(text) {
+    const matches = [];
+    for (const pattern of INJECTION_PATTERNS) {
+        const found = text.match(pattern);
+        if (found) {
+            matches.push(found[0]);
+        }
+    }
+    if (matches.length > 0) {
+        return { blocked: true, reason: "prompt injection pattern detected", matches };
+    }
+    return { blocked: false };
+}
+export function filterCustom(text) {
+    const matches = [];
+    for (const pattern of customPatterns) {
+        const found = text.match(pattern);
+        if (found) {
+            matches.push(found[0]);
+        }
+    }
+    if (matches.length > 0) {
+        return { blocked: true, reason: "custom pattern matched", matches };
+    }
+    return { blocked: false };
+}
+export function applyContentFilter(text, options = {}) {
+    const { pii = true, injection = true, custom = true } = options;
+    if (pii) {
+        const r = filterPII(text);
+        if (r.blocked)
+            return r;
+    }
+    if (injection) {
+        const r = filterInjection(text);
+        if (r.blocked)
+            return r;
+    }
+    if (custom) {
+        const r = filterCustom(text);
+        if (r.blocked)
+            return r;
+    }
+    return { blocked: false };
+}

package/dist/guard/permissions.d.ts

@@ -0,0 +1,17 @@
+export interface PermissionRule {
+    tool_pattern: string;
+    decision: "allow" | "deny" | "ask";
+    reason?: string;
+}
+export interface PermissionResult {
+    decision: "allow" | "deny" | "ask";
+    reason?: string;
+    matched_rule?: string;
+}
+export declare class PermissionMatrix {
+    private defaultDecision;
+    private rules;
+    constructor(defaultDecision?: "allow" | "deny" | "ask", rules?: PermissionRule[]);
+    evaluate(toolName: string): PermissionResult;
+}
+//# sourceMappingURL=permissions.d.ts.map

package/dist/guard/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/guard/permissions.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,eAAe,CAA2B;IAClD,OAAO,CAAC,KAAK,CAAmB;gBAEpB,eAAe,GAAE,OAAO,GAAG,MAAM,GAAG,KAAe,EAAE,KAAK,GAAE,cAAc,EAAO;IAK7F,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB;CAY7C"}

package/dist/guard/permissions.js

@@ -0,0 +1,54 @@
+// ============================================================
+// 轻灵 - Guard M2: 工具权限矩阵
+// 配置驱动的 per-tool allow/deny/ask，glob 匹配
+// ============================================================
+export class PermissionMatrix {
+    defaultDecision;
+    rules;
+    constructor(defaultDecision = "allow", rules = []) {
+        this.defaultDecision = defaultDecision;
+        this.rules = rules;
+    }
+    evaluate(toolName) {
+        for (const rule of this.rules) {
+            if (matchGlob(rule.tool_pattern, toolName)) {
+                return {
+                    decision: rule.decision,
+                    reason: rule.reason,
+                    matched_rule: rule.tool_pattern,
+                };
+            }
+        }
+        return { decision: this.defaultDecision };
+    }
+}
+function matchGlob(pattern, value) {
+    if (pattern === "*")
+        return true;
+    if (pattern === value)
+        return true;
+    // Convert glob to regex: * -> .*, ? -> ., escape rest
+    let regex = "^";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            regex += ".*";
+        }
+        else if (ch === "?") {
+            regex += ".";
+        }
+        else if (/[.+^${}()|[\]\\]/.test(ch)) {
+            regex += "\\" + ch;
+        }
+        else {
+            regex += ch;
+        }
+    }
+    regex += "$";
+    try {
+        return new RegExp(regex).test(value);
+    }
+    catch {
+        return pattern === value;
+    }
+}

package/dist/guard/rate-limit.d.ts

@@ -0,0 +1,14 @@
+export interface RateLimitResult {
+    allowed: boolean;
+    retryAfterMs?: number;
+}
+export declare class RateLimiter {
+    private windowMs;
+    private maxPerWindow;
+    private windows;
+    constructor(maxPerMinute?: number, windowMs?: number);
+    check(tool: string, sessionId: string): RateLimitResult;
+    reset(tool?: string, sessionId?: string): void;
+    getWindowSize(): number;
+}
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/guard/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/guard/rate-limit.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAkC;gBAErC,YAAY,GAAE,MAAW,EAAE,QAAQ,GAAE,MAAe;IAKhE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe;IAwBvD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAa9C,aAAa,IAAI,MAAM;CAGxB"}

package/dist/guard/rate-limit.js

@@ -0,0 +1,47 @@
+// ============================================================
+// 轻灵 - Guard M2: 滑动窗口速率限制器
+// per (tool, session) 维度，60s 窗口
+// ============================================================
+export class RateLimiter {
+    windowMs;
+    maxPerWindow;
+    windows = new Map();
+    constructor(maxPerMinute = 30, windowMs = 60_000) {
+        this.maxPerWindow = maxPerMinute;
+        this.windowMs = windowMs;
+    }
+    check(tool, sessionId) {
+        const key = tool + ":" + sessionId;
+        const now = Date.now();
+        const cutoff = now - this.windowMs;
+        let entry = this.windows.get(key);
+        if (!entry) {
+            entry = { timestamps: [] };
+            this.windows.set(key, entry);
+        }
+        // Prune expired timestamps
+        entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+        if (entry.timestamps.length >= this.maxPerWindow) {
+            const oldest = entry.timestamps[0];
+            const retryAfterMs = oldest + this.windowMs - now;
+            return { allowed: false, retryAfterMs: Math.max(0, retryAfterMs) };
+        }
+        entry.timestamps.push(now);
+        return { allowed: true };
+    }
+    reset(tool, sessionId) {
+        if (!tool && !sessionId) {
+            this.windows.clear();
+            return;
+        }
+        for (const key of this.windows.keys()) {
+            const [t, s] = key.split(":");
+            if ((!tool || t === tool) && (!sessionId || s === sessionId)) {
+                this.windows.delete(key);
+            }
+        }
+    }
+    getWindowSize() {
+        return this.windows.size;
+    }
+}

package/dist/guard.d.ts

@@ -0,0 +1,21 @@
+import type { GuardConfig } from "./config.js";
+export type GuardCategory = "network" | "redaction" | "permission" | "rate_limit" | "content_filter";
+export interface GuardDecision {
+    allowed: boolean;
+    reason?: string;
+    category?: GuardCategory;
+}
+export interface GuardAuditEvent {
+    tool: string;
+    action: "allow" | "deny";
+    category?: GuardCategory;
+    target?: string;
+    reason?: string;
+    status?: number;
+}
+export declare function redactText(text: string, guard: GuardConfig): string;
+export type NetworkGuardMode = "strict" | "open" | "deny";
+export declare function resolveNetworkGuardMode(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): NetworkGuardMode;
+export declare function checkUrlFetchPolicy(url: URL, guard: GuardConfig, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): Promise<GuardDecision>;
+export declare function appendGuardAudit(guard: GuardConfig, event: GuardAuditEvent): Promise<void>;
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAErG,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAuBnE;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1D,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,gBAAgB,CAOlB;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,WAAW,EAClB,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,OAAO,CAAC,aAAa,CAAC,CA2DxB;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAahG"}

package/dist/guard.js

@@ -0,0 +1,144 @@
+import { lookup } from "dns/promises";
+import * as net from "net";
+import { appendFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+export function redactText(text, guard) {
+    if (!guard.enabled || !guard.redaction.enabled)
+        return text;
+    let out = text;
+    // Built-in masks
+    const builtins = [
+        /\b(sk-[a-zA-Z0-9]{16,})\b/g,
+        /\b(Bearer\s+[A-Za-z0-9\-._~+/]+=*)\b/g,
+        /\b(AKIA[0-9A-Z]{16})\b/g,
+    ];
+    for (const pattern of builtins) {
+        out = out.replace(pattern, "[REDACTED]");
+    }
+    for (const raw of guard.redaction.patterns) {
+        try {
+            const re = new RegExp(raw, "g");
+            out = out.replace(re, "[REDACTED]");
+        }
+        catch {
+            // ignore invalid pattern
+        }
+    }
+    return out;
+}
+export function resolveNetworkGuardMode(env = process.env) {
+    const raw = String(env.QLING_GUARD_NETWORK_MODE ?? "strict").trim().toLowerCase();
+    if (raw === "deny" || raw === "deny_all" || raw === "off" || raw === "none" || raw === "block") {
+        return "deny";
+    }
+    if (raw === "open" || raw === "permissive" || raw === "http")
+        return "open";
+    return "strict";
+}
+export async function checkUrlFetchPolicy(url, guard, env = process.env) {
+    if (!guard.enabled)
+        return { allowed: true };
+    const mode = resolveNetworkGuardMode(env);
+    if (mode === "deny") {
+        return {
+            allowed: false,
+            category: "network",
+            reason: "network mode=deny: all outbound fetches blocked (QLING_GUARD_NETWORK_MODE)",
+        };
+    }
+    const policy = guard.network.url_fetch;
+    const href = url.toString();
+    if (mode === "open") {
+        // 允许 http/https，仍受私网策略约束；忽略自定义前缀收紧
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            return {
+                allowed: false,
+                category: "network",
+                reason: `unsupported protocol in open mode: ${url.protocol}`,
+            };
+        }
+    }
+    else if (!policy.allowed_url_prefixes.some((prefix) => href.startsWith(prefix))) {
+        return {
+            allowed: false,
+            category: "network",
+            reason: `url not allowed by prefix policy: ${href}`,
+        };
+    }
+    if (policy.deny_private_ips) {
+        const host = url.hostname;
+        if (isLiteralPrivateHost(host)) {
+            return {
+                allowed: false,
+                category: "network",
+                reason: `private ip host blocked: ${host}`,
+            };
+        }
+        try {
+            const ips = await lookup(host, { all: true });
+            for (const ip of ips) {
+                if (isPrivateIp(ip.address)) {
+                    return {
+                        allowed: false,
+                        category: "network",
+                        reason: `resolved private ip blocked: ${ip.address}`,
+                    };
+                }
+            }
+        }
+        catch {
+            // DNS failure is handled by caller fetch path.
+        }
+    }
+    return { allowed: true };
+}
+export async function appendGuardAudit(guard, event) {
+    if (!guard.enabled)
+        return;
+    const line = JSON.stringify({
+        ts: new Date().toISOString(),
+        ...event,
+    });
+    try {
+        const targetPath = guard.audit.jsonl_path;
+        await mkdir(dirname(targetPath), { recursive: true });
+        await appendFile(targetPath, line + "\n", "utf-8");
+    }
+    catch {
+        // 审计写入失败不阻断主流程
+    }
+}
+function isLiteralPrivateHost(hostname) {
+    if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1")
+        return true;
+    if (net.isIP(hostname) === 0)
+        return false;
+    return isPrivateIp(hostname);
+}
+function isPrivateIp(ip) {
+    if (net.isIP(ip) === 4) {
+        const [a, b] = ip.split(".").map((x) => Number(x));
+        if (a === 10)
+            return true;
+        if (a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 0)
+            return true;
+    }
+    if (net.isIP(ip) === 6) {
+        const lower = ip.toLowerCase();
+        if (lower === "::1")
+            return true;
+        if (lower.startsWith("fc") || lower.startsWith("fd"))
+            return true; // ULA
+        if (lower.startsWith("fe80"))
+            return true; // link-local
+    }
+    return false;
+}