ysagc-agent 0.2.0 → 0.4.0

package/dist/path-utils.d.ts

@@ -0,0 +1,44 @@
+/** Thrown when a path is empty, escapes the allowed root, or targets a
+ * Windows-reserved / sensitive location. */
+export declare class PathError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** True when a single path segment (ignoring its extension) is a Windows
+ * reserved device name such as CON or COM1. */
+export declare function isWindowsReservedName(segment: string): boolean;
+/**
+ * Resolve the longest existing ancestor's real path and re-append the
+ * not-yet-existing tail. This keeps canonicalisation correct for both files
+ * that already exist (symlinks resolved) and files about to be created
+ * (their existing parent's symlinks resolved), which prevents escaping the
+ * root through a symlink.
+ */
+export declare function realpathSafe(p: string): string;
+/**
+ * Produce a canonical, absolute, symlink-aware path. Resolves `..`, normalises
+ * separators, resolves symlinks on the existing prefix, strips the Windows
+ * `\\?\` prefix, and (on Windows) detects reserved device names and trailing
+ * dot/space aliases. `~` and environment variables are NOT expanded.
+ */
+export declare function canonicalize(p: string, cwd?: string): string;
+export interface WithinRootOptions {
+    /** Allow the candidate to be exactly equal to the root (e.g. listing the
+     * root itself). Defaults to false so writes to the root are rejected. */
+    allowEqual?: boolean;
+}
+/**
+ * Strictly check that `candidate` is under `root`. Both are canonicalised
+ * first, so `..` escapes and symlink escapes are detected regardless of the
+ * original spelling. By default a candidate equal to the root is rejected.
+ */
+export declare function isWithinRoot(root: string, candidate: string, opts?: WithinRootOptions): boolean;
+/**
+ * Assert that `candidate` is inside `root`. Returns the canonical candidate
+ * path, or throws a {@link PathError} if it is outside the root.
+ */
+export declare function assertInsideRoot(root: string, candidate: string, opts?: WithinRootOptions): string;
+/** Resolve a tool-provided relative path against `cwd` and validate it stays
+ * inside the root. */
+export declare function safeResolve(root: string, p: string, cwd?: string, opts?: WithinRootOptions): string;
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAGA;4CAC4C;AAC5C,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AA8BD;+CAC+C;AAC/C,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CA0B9C;AAaD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAyB5D;AAED,MAAM,WAAW,iBAAiB;IAChC;6EACyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAenG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAUtG;AAED;sBACsB;AACtB,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAGvG"}

package/dist/path-utils.js

@@ -0,0 +1,206 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PathError = void 0;
+exports.isWindowsReservedName = isWindowsReservedName;
+exports.realpathSafe = realpathSafe;
+exports.canonicalize = canonicalize;
+exports.isWithinRoot = isWithinRoot;
+exports.assertInsideRoot = assertInsideRoot;
+exports.safeResolve = safeResolve;
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+/** Thrown when a path is empty, escapes the allowed root, or targets a
+ * Windows-reserved / sensitive location. */
+class PathError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'PathError';
+        this.code = code;
+    }
+}
+exports.PathError = PathError;
+/** Windows reserved device names (base name, case-insensitive). */
+const WINDOWS_RESERVED = new Set([
+    'CON',
+    'PRN',
+    'AUX',
+    'NUL',
+    'COM1',
+    'COM2',
+    'COM3',
+    'COM4',
+    'COM5',
+    'COM6',
+    'COM7',
+    'COM8',
+    'COM9',
+    'LPT1',
+    'LPT2',
+    'LPT3',
+    'LPT4',
+    'LPT5',
+    'LPT6',
+    'LPT7',
+    'LPT8',
+    'LPT9',
+]);
+const IS_WINDOWS = process.platform === 'win32';
+/** True when a single path segment (ignoring its extension) is a Windows
+ * reserved device name such as CON or COM1. */
+function isWindowsReservedName(segment) {
+    const base = String(segment ?? '').trim().split('.')[0].toUpperCase();
+    return WINDOWS_RESERVED.has(base);
+}
+/**
+ * Resolve the longest existing ancestor's real path and re-append the
+ * not-yet-existing tail. This keeps canonicalisation correct for both files
+ * that already exist (symlinks resolved) and files about to be created
+ * (their existing parent's symlinks resolved), which prevents escaping the
+ * root through a symlink.
+ */
+function realpathSafe(p) {
+    const abs = path.resolve(p);
+    try {
+        const real = fs.realpathSync(abs);
+        return real;
+    }
+    catch {
+        // The path does not fully exist; walk up to the deepest existing ancestor.
+        let existing = abs;
+        const tail = [];
+        // Guard against non-finite loops.
+        for (let i = 0; i < 4096; i++) {
+            const parent = path.dirname(existing);
+            if (existing === parent)
+                break;
+            if (fs.existsSync(existing)) {
+                try {
+                    const real = fs.realpathSync(existing);
+                    return tail.length ? path.resolve(real, ...tail) : real;
+                }
+                catch {
+                    // parent was removed between check and realpath; continue upward
+                }
+            }
+            tail.unshift(path.basename(existing));
+            existing = parent;
+        }
+    }
+    return abs;
+}
+/** Strip trailing dots and spaces from each path segment (Windows aliases). */
+function stripWindowsTrailing(p) {
+    const parts = p.split(path.sep);
+    const cleaned = parts.map((part, idx) => {
+        if (idx === 0)
+            return part; // drive/root prefix
+        const stripped = part.replace(/[ \t.\u00A0]+$/u, '');
+        return stripped === '' ? part : stripped;
+    });
+    return cleaned.join(path.sep);
+}
+/**
+ * Produce a canonical, absolute, symlink-aware path. Resolves `..`, normalises
+ * separators, resolves symlinks on the existing prefix, strips the Windows
+ * `\\?\` prefix, and (on Windows) detects reserved device names and trailing
+ * dot/space aliases. `~` and environment variables are NOT expanded.
+ */
+function canonicalize(p, cwd) {
+    let raw = String(p ?? '').trim();
+    if (raw === '') {
+        throw new PathError('ERR_EMPTY_PATH', 'Path is empty');
+    }
+    // Strip the Windows long-path prefix `\\?\`.
+    raw = raw.replace(/^\\\\\?\\/, '');
+    // Some shells pass `\\?\UNC\`; collapse to a UNC path.
+    raw = raw.replace(/^\\\\\?\\UNC\\/, '\\\\');
+    const base = cwd && cwd.trim() !== '' ? cwd : process.cwd();
+    const abs = path.resolve(base, raw);
+    let normalized = path.normalize(abs);
+    if (IS_WINDOWS) {
+        normalized = stripWindowsTrailing(normalized);
+        for (const segment of normalized.split(path.sep)) {
+            if (segment && isWindowsReservedName(segment)) {
+                throw new PathError('ERR_RESERVED_NAME', `Path uses a reserved Windows name: ${segment}`);
+            }
+        }
+    }
+    return realpathSafe(normalized);
+}
+/**
+ * Strictly check that `candidate` is under `root`. Both are canonicalised
+ * first, so `..` escapes and symlink escapes are detected regardless of the
+ * original spelling. By default a candidate equal to the root is rejected.
+ */
+function isWithinRoot(root, candidate, opts = {}) {
+    const allowEqual = opts.allowEqual ?? false;
+    let rootC;
+    let candC;
+    try {
+        rootC = canonicalize(root);
+        candC = canonicalize(candidate);
+    }
+    catch {
+        return false;
+    }
+    const rel = path.relative(rootC, candC);
+    if (rel === '')
+        return allowEqual;
+    if (rel === '..' || rel.startsWith('..' + path.sep))
+        return false;
+    if (path.isAbsolute(rel))
+        return false;
+    return true;
+}
+/**
+ * Assert that `candidate` is inside `root`. Returns the canonical candidate
+ * path, or throws a {@link PathError} if it is outside the root.
+ */
+function assertInsideRoot(root, candidate, opts = {}) {
+    const rootC = canonicalize(root);
+    const candC = canonicalize(candidate);
+    if (!isWithinRoot(rootC, candC, opts)) {
+        throw new PathError('ERR_OUTSIDE_ROOT', `Path is outside the authorised root: ${candidate} (root: ${rootC})`);
+    }
+    return candC;
+}
+/** Resolve a tool-provided relative path against `cwd` and validate it stays
+ * inside the root. */
+function safeResolve(root, p, cwd, opts = {}) {
+    const resolved = canonicalize(p, cwd);
+    return assertInsideRoot(root, resolved, opts);
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/path-utils.js.map

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

package/dist/protocol.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Wire protocol for the ysagc platform agent channel. Messages are JSON text
+ * frames. Client-to-server and server-to-client message sets are kept
+ * separate so unknown or miscast frames are rejected as malformed.
+ */
+export type ClientState = 'online' | 'busy' | 'error';
+export interface HelloMessage {
+    type: 'hello';
+    token: string;
+    deviceId: string;
+    version: string;
+    platform: string;
+}
+export interface PongMessage {
+    type: 'pong';
+    t?: number;
+}
+export interface ToolResultMessage {
+    type: 'tool_result';
+    jobId: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+    durationMs: number;
+    /** Set when the idempotency cache was the source of the result. */
+    cached?: boolean;
+}
+export interface StatusMessage {
+    type: 'status';
+    state: ClientState;
+    sessionId?: string;
+    jobId?: string;
+    ts?: number;
+}
+export interface WelcomeMessage {
+    type: 'welcome';
+    sessionId: string;
+}
+export interface PingMessage {
+    type: 'ping';
+    t?: number;
+}
+export interface ToolCallMessage {
+    type: 'tool_call';
+    jobId: string;
+    idempotencyKey?: string;
+    tool: string;
+    args: Record<string, unknown>;
+}
+export interface CancelMessage {
+    type: 'cancel';
+    jobId: string;
+}
+export type ClientMessage = HelloMessage | PongMessage | ToolResultMessage | StatusMessage;
+export type ServerMessage = WelcomeMessage | PingMessage | ToolCallMessage | CancelMessage;
+export type PlatformMessage = ClientMessage | ServerMessage;
+/** Serialise a message to a JSON wire frame. */
+export declare function encodeMessage(msg: PlatformMessage): string;
+/** Convert raw frame bytes/strings into a parsed server message. Returns null
+ * when the frame is not a well-formed, known server message. */
+export declare function decodeMessage(data: string | Buffer | ArrayBuffer | DataView | Uint8Array): ServerMessage | null;
+export declare function isToolCall(msg: ServerMessage): msg is ToolCallMessage;
+export declare function isPing(msg: ServerMessage): msg is PingMessage;
+export declare function isCancel(msg: ServerMessage): msg is CancelMessage;
+export declare function isWelcome(msg: ServerMessage): msg is WelcomeMessage;
+/**
+ * Canonical, deterministic JSON serialisation (object keys are sorted) so the
+ * same tool/args always produce the same cache key irrespective of key order.
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * Compute a stable idempotency key for a tool invocation. When the platform
+ * supplies a key (for the same job retried after a crash) it is combined with
+ * the tool + arguments so two logically different jobs never collide.
+ */
+export declare function computeIdempotencyKey(tool: string, args: Record<string, unknown>, idempotencyKey?: string): string;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,WAAW,GAAG,iBAAiB,GAAG,aAAa,CAAC;AAC3F,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,WAAW,GAAG,eAAe,GAAG,aAAa,CAAC;AAC3F,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,aAAa,CAAC;AAI5D,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAE1D;AAED;gEACgE;AAChE,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAC1D,aAAa,GAAG,IAAI,CAwBtB;AAQD,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,IAAI,eAAe,CAErE;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,IAAI,WAAW,CAE7D;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,IAAI,aAAa,CAEjE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,IAAI,cAAc,CAEnE;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWtD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,cAAc,CAAC,EAAE,MAAM,GACtB,MAAM,CAOR"}

package/dist/protocol.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeMessage = encodeMessage;
+exports.decodeMessage = decodeMessage;
+exports.isToolCall = isToolCall;
+exports.isPing = isPing;
+exports.isCancel = isCancel;
+exports.isWelcome = isWelcome;
+exports.stableStringify = stableStringify;
+exports.computeIdempotencyKey = computeIdempotencyKey;
+const node_crypto_1 = require("node:crypto");
+const SERVER_TYPES = new Set(['welcome', 'ping', 'tool_call', 'cancel']);
+/** Serialise a message to a JSON wire frame. */
+function encodeMessage(msg) {
+    return JSON.stringify(msg);
+}
+/** Convert raw frame bytes/strings into a parsed server message. Returns null
+ * when the frame is not a well-formed, known server message. */
+function decodeMessage(data) {
+    let buf;
+    if (typeof data === 'string') {
+        buf = Buffer.from(data, 'utf8');
+    }
+    else if (data instanceof ArrayBuffer) {
+        buf = Buffer.from(new Uint8Array(data));
+    }
+    else if (data instanceof DataView) {
+        buf = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    }
+    else {
+        buf = Buffer.from(data);
+    }
+    const text = buf.toString('utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    const type = parsed.type;
+    if (typeof type !== 'string' || !SERVER_TYPES.has(type))
+        return null;
+    return parsed;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// --- type guards -----------------------------------------------------------
+function isToolCall(msg) {
+    return msg.type === 'tool_call';
+}
+function isPing(msg) {
+    return msg.type === 'ping';
+}
+function isCancel(msg) {
+    return msg.type === 'cancel';
+}
+function isWelcome(msg) {
+    return msg.type === 'welcome';
+}
+// --- idempotency -----------------------------------------------------------
+/**
+ * Canonical, deterministic JSON serialisation (object keys are sorted) so the
+ * same tool/args always produce the same cache key irrespective of key order.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => stableStringify(v)).join(',') + ']';
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+    return '{' + parts.join(',') + '}';
+}
+/**
+ * Compute a stable idempotency key for a tool invocation. When the platform
+ * supplies a key (for the same job retried after a crash) it is combined with
+ * the tool + arguments so two logically different jobs never collide.
+ */
+function computeIdempotencyKey(tool, args, idempotencyKey) {
+    const payload = stableStringify({
+        tool,
+        args,
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+    });
+    return (0, node_crypto_1.createHash)('sha256').update(payload).digest('hex');
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

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

package/dist/security.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Security helpers: dangerous-command detection, sensitive-path detection and
+ * secret masking. These are intentionally conservative — when in doubt the
+ * path/command is treated as unsafe.
+ */
+export type DangerSeverity = 'none' | 'danger' | 'critical';
+export interface DangerAssessment {
+    /** True when the command must never be executed automatically. */
+    danger: boolean;
+    severity: DangerSeverity;
+    /** Human-readable reason for the assessment. */
+    reason: string;
+}
+/**
+ * Assess whether a shell command is too dangerous to run automatically.
+ * Cross-platform (bash / powershell / cmd). Returns a severity and reason.
+ */
+export declare function isDangerCommand(command: string): DangerAssessment;
+/**
+ * Whether a (canonical absolute) path should never be read/written by a tool.
+ * These are blocked no matter what permission mode is in effect.
+ */
+export declare function isSensitivePath(p: string): boolean;
+/** Emitted value when any secret has been redacted. */
+export declare const MASK = "***";
+/**
+ * Redact secrets from a string: provider keys, bearer tokens, JWTs, private
+ * keys, and `key=value` / `key: value` pairs for obvious secret names. Used
+ * before logging or returning tool output so internal keys never leak.
+ */
+export declare function maskSecrets(text: string): string;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,cAAc,CAAC;IACzB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;CAChB;AA8HD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAejE;AA8BD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAOlD;AAED,uDAAuD;AACvD,eAAO,MAAM,IAAI,QAAQ,CAAC;AAE1B;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwChD"}