@nanhara/hara 0.121.1 → 0.122.1

package/dist/security/private-state.js

@@ -0,0 +1,299 @@
+// Owner-only migration for Hara's local control plane. New writers should still create private files
+// directly, but this repairs installations created by older releases and makes ~/.hara non-traversable by
+// other local users before credentials/session state are read.
+import { closeSync, chmodSync, constants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, realpathSync, unlinkSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve, sep } from "node:path";
+import { FileReadLimitError, MAX_EDIT_READ_BYTES, openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync, } from "../fs-read.js";
+const PRIVATE_TREES = new Set(["sessions", "checkpoints", "index", "gateway", "cron", "weixin"]);
+const tightenedHomes = new Set();
+const DEFAULT_MIGRATION_CAP = 50_000;
+function isMissing(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+function chmodPrivate(path, mode) {
+    try {
+        chmodSync(path, mode);
+    }
+    catch (error) {
+        // Windows does not implement POSIX ownership modes. On POSIX, a failed repair is a security failure:
+        // propagate it so startup can retry instead of permanently caching an incomplete migration.
+        if (process.platform !== "win32")
+            throw error;
+    }
+}
+function checkedPrivateComponent(component) {
+    if (!component || component === "." || component === ".." || basename(component) !== component || component.includes(sep) || component.includes("\0")) {
+        throw new Error(`invalid private Hara state path component '${component}'`);
+    }
+    return component;
+}
+function verifyPrivateDirectory(identity) {
+    const info = lstatSync(identity.path);
+    if (!info.isDirectory()
+        || info.isSymbolicLink()
+        || info.dev !== identity.dev
+        || info.ino !== identity.ino
+        || realpathSync.native(identity.path) !== identity.path)
+        throw new Error(`private Hara state directory changed: '${identity.path}'`);
+}
+/** Tighten one directory through a no-follow descriptor so a pre-existing link is never chmod'd. */
+function inspectPrivateDirectory(path) {
+    const before = lstatSync(path);
+    if (!before.isDirectory() || before.isSymbolicLink()) {
+        throw new Error(`refusing private Hara state directory: '${path}' is not a real directory`);
+    }
+    if (realpathSync.native(path) !== path) {
+        throw new Error(`refusing private Hara state directory: '${path}' contains a symbolic-link component`);
+    }
+    return { path, dev: before.dev, ino: before.ino };
+}
+/** Tighten one directory through a no-follow descriptor so a pre-existing link is never chmod'd. */
+function verifyAndTightenPrivateDirectory(path) {
+    const inspected = inspectPrivateDirectory(path);
+    // Opening a directory descriptor is not portable to Windows. There, re-checking the link identity around
+    // the validation retains the same fail-closed preseed policy and POSIX ownership bits do not apply;
+    // POSIX uses O_NOFOLLOW + fchmod.
+    if (process.platform === "win32") {
+        // no POSIX ownership mode to repair
+    }
+    else {
+        const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+        const directoryOnly = typeof constants.O_DIRECTORY === "number" ? constants.O_DIRECTORY : 0;
+        const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | noFollow | directoryOnly);
+        try {
+            const opened = fstatSync(fd);
+            if (!opened.isDirectory() || opened.dev !== inspected.dev || opened.ino !== inspected.ino) {
+                throw new Error(`private Hara state directory changed while opening: '${path}'`);
+            }
+            fchmodSync(fd, 0o700);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    const after = lstatSync(path);
+    if (after.dev !== inspected.dev || after.ino !== inspected.ino) {
+        throw new Error(`private Hara state directory changed while tightening: '${path}'`);
+    }
+    const identity = { path, dev: inspected.dev, ino: inspected.ino };
+    verifyPrivateDirectory(identity);
+    return identity;
+}
+/**
+ * Create a private control-plane subdirectory one component at a time below a canonical trusted base.
+ * Existing `.hara`/child components must be real directories; recursive mkdir/chmod is intentionally
+ * avoided because either operation would follow a malicious repository-provided link.
+ */
+export function ensurePrivateStateSubdirectory(base, components, tightenExistingFrom = 0) {
+    if (!Number.isInteger(tightenExistingFrom) || tightenExistingFrom < 0 || tightenExistingFrom > components.length) {
+        throw new TypeError("private Hara state tighten boundary is out of range");
+    }
+    let current = realpathSync.native(resolve(base));
+    const baseInfo = lstatSync(current);
+    if (!baseInfo.isDirectory() || baseInfo.isSymbolicLink()) {
+        throw new Error(`private Hara state base is not a canonical directory: '${current}'`);
+    }
+    let parent = { path: current, dev: baseInfo.dev, ino: baseInfo.ino };
+    verifyPrivateDirectory(parent);
+    for (let index = 0; index < components.length; index++) {
+        const raw = components[index];
+        const component = checkedPrivateComponent(raw);
+        verifyPrivateDirectory(parent);
+        current = join(current, component);
+        try {
+            const existing = lstatSync(current);
+            if (!existing.isDirectory() || existing.isSymbolicLink()) {
+                throw new Error(`refusing private Hara state directory: '${current}' is not a real directory`);
+            }
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT")
+                throw error;
+            // Parent identity is checked immediately before the namespace mutation. mkdir is non-recursive and
+            // therefore cannot walk through a newly supplied child link.
+            verifyPrivateDirectory(parent);
+            try {
+                mkdirSync(current, { mode: 0o700 });
+            }
+            catch (mkdirError) {
+                if (mkdirError?.code !== "EEXIST")
+                    throw mkdirError;
+            }
+        }
+        parent = index >= tightenExistingFrom
+            ? verifyAndTightenPrivateDirectory(current)
+            : inspectPrivateDirectory(current);
+        verifyPrivateDirectory(parent);
+    }
+    return parent;
+}
+/** Open/read one internal state file without following aliases, reject hard links, and repair mode by fd. */
+export async function readPrivateStateFileSnapshot(path, maxBytes = MAX_EDIT_READ_BYTES) {
+    const requested = Number.isFinite(maxBytes) ? Math.floor(maxBytes) : MAX_EDIT_READ_BYTES;
+    const limit = Math.min(MAX_EDIT_READ_BYTES, Math.max(1, requested));
+    let verified;
+    try {
+        verified = await openVerifiedRegularFileNoFollow(path, {
+            action: "read private Hara state",
+            rejectHardLinks: true,
+            protectSensitive: false,
+        });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        const { handle } = verified;
+        try {
+            await handle.chmod(0o600);
+        }
+        catch (error) {
+            if (process.platform !== "win32")
+                throw error;
+        }
+        const before = await handle.stat();
+        if (before.size > limit)
+            throw new FileReadLimitError(path, limit);
+        const chunks = [];
+        let total = 0;
+        let position = 0;
+        while (total <= limit) {
+            const want = Math.min(64 * 1024, limit + 1 - total);
+            const buffer = Buffer.allocUnsafe(want);
+            const { bytesRead } = await handle.read(buffer, 0, want, position);
+            if (!bytesRead)
+                break;
+            chunks.push(buffer.subarray(0, bytesRead));
+            total += bytesRead;
+            position += bytesRead;
+        }
+        if (total > limit)
+            throw new FileReadLimitError(path, limit);
+        const after = await handle.stat();
+        verifyOpenedRegularFileSync(path, after, {
+            action: "read private Hara state",
+            rejectHardLinks: true,
+            protectSensitive: false,
+        });
+        if (after.dev !== before.dev
+            || after.ino !== before.ino
+            || after.size !== before.size
+            || after.mtimeMs !== before.mtimeMs
+            || after.ctimeMs !== before.ctimeMs)
+            throw new Error(`private Hara state file changed while reading: '${path}'`);
+        return {
+            text: Buffer.concat(chunks, total).toString("utf8"),
+            dev: after.dev,
+            ino: after.ino,
+            mode: after.mode & 0o777,
+            nlink: after.nlink,
+            size: after.size,
+            mtimeMs: after.mtimeMs,
+            ctimeMs: after.ctimeMs,
+        };
+    }
+    finally {
+        await verified.handle.close().catch(() => { });
+    }
+}
+/** Remove only the exact single-link inode previously read from the same still-bound private directory. */
+export function removePrivateStateFile(path, expected, directory) {
+    verifyPrivateDirectory(directory);
+    if (resolve(path) !== join(directory.path, basename(path))) {
+        throw new Error(`private Hara state file is outside '${directory.path}'`);
+    }
+    const current = lstatSync(path);
+    if (!current.isFile()
+        || current.isSymbolicLink()
+        || current.nlink !== 1
+        || current.dev !== expected.dev
+        || current.ino !== expected.ino
+        || (current.mode & 0o777) !== expected.mode
+        || current.size !== expected.size
+        || current.mtimeMs !== expected.mtimeMs
+        || current.ctimeMs !== expected.ctimeMs)
+        throw new Error(`private Hara state file changed before removal: '${path}'`);
+    verifyPrivateDirectory(directory);
+    unlinkSync(path);
+}
+function consumeBudget(path, budget) {
+    budget.seen++;
+    if (budget.seen > budget.cap) {
+        throw new Error(`private Hara state migration exceeded ${budget.cap} entries at '${path}'; ` +
+            "refusing to cache an incomplete permission repair");
+    }
+}
+function tightenTree(root, budget) {
+    const stack = [root];
+    while (stack.length) {
+        const path = stack.pop();
+        consumeBudget(path, budget);
+        let info;
+        try {
+            info = lstatSync(path);
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue; // a concurrently removed derived file needs no repair
+            throw error;
+        }
+        if (info.isSymbolicLink())
+            continue; // never chmod a target chosen through a replaceable link
+        if (info.isDirectory()) {
+            chmodPrivate(path, 0o700);
+            const entries = readdirSync(path);
+            for (const entry of entries)
+                stack.push(join(path, entry));
+        }
+        else if (info.isFile()) {
+            chmodPrivate(path, 0o600);
+        }
+    }
+}
+/** Repair one Hara home. Exported with an injected path for offline tests. */
+export function tightenPrivateHaraState(home = homedir(), cap = DEFAULT_MIGRATION_CAP) {
+    if (!Number.isSafeInteger(cap) || cap < 1)
+        throw new TypeError("private Hara state migration cap must be a positive integer");
+    const root = join(home, ".hara");
+    let rootInfo;
+    try {
+        rootInfo = lstatSync(root);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        rootInfo = lstatSync(root);
+    }
+    // `chmod` follows symlinks. Reject the control-plane root before touching it so ~/.hara cannot be
+    // redirected to an unrelated user directory by a local link/race left from an older installation.
+    if (rootInfo.isSymbolicLink())
+        throw new Error(`refusing private Hara state migration: '${root}' is a symbolic link`);
+    if (!rootInfo.isDirectory())
+        throw new Error(`refusing private Hara state migration: '${root}' is not a directory`);
+    chmodPrivate(root, 0o700);
+    const budget = { seen: 0, cap };
+    const entries = readdirSync(root, { withFileTypes: true });
+    for (const entry of entries) {
+        const path = join(root, entry.name);
+        // Re-check with lstat inside tightenTree instead of trusting a possibly stale Dirent. It also skips
+        // symlinks, including top-level file links, without following their targets.
+        if (entry.isFile() || (entry.isDirectory() && PRIVATE_TREES.has(entry.name)))
+            tightenTree(path, budget);
+    }
+}
+/** Process-once startup migration; repeated loadConfig calls stay cheap. */
+export function ensurePrivateHaraState(home = homedir(), cap = DEFAULT_MIGRATION_CAP) {
+    if (tightenedHomes.has(home))
+        return;
+    tightenPrivateHaraState(home, cap);
+    // Cache only after the whole migration succeeds. Cap/permission failures are therefore retryable.
+    tightenedHomes.add(home);
+}
+/** @internal test helper. */
+export function resetPrivateHaraStateForTests() {
+    tightenedHomes.clear();
+}

package/dist/security/project-trust.js

@@ -0,0 +1,6 @@
+// One process-wide, launch-time trust decision for repository-controlled configuration and identity pins.
+// Capture at module evaluation so later code (including extensions) cannot widen trust by mutating process.env.
+const trustedAtStartup = process.env.HARA_TRUST_PROJECT_CONFIG === "1";
+export function projectRepositoryTrustedAtStartup() {
+    return trustedAtStartup;
+}

package/dist/security/secrets.js

@@ -1,6 +1,8 @@
 /** Shared secret redaction for anything that may leave the live model context (session JSON, public
  *  feedback, logs). Deliberately conservative: a false positive hides a value in a local transcript;
  *  a false negative leaves a credential on disk. */
+const CREDENTIAL_NAME = String.raw `(?:[A-Za-z][A-Za-z0-9_.-]*(?:api[_-]?key|apikey|secret|token|password|passwd)[A-Za-z0-9_.-]*|(?:api[_-]?key|apikey|secret|token|password|passwd)[A-Za-z0-9_.-]*)`;
+const CREDENTIAL_FLAG = String.raw `--?(?:api[-_]?key|token|secret|password|passwd)`;
 const PATTERNS = [
     {
         label: "private-key",
@@ -9,6 +11,11 @@ const PATTERNS = [
     },
     { label: "sk-key", re: /\bsk-[A-Za-z0-9_-]{8,}\b/g, replace: "sk-***" },
     { label: "github-token", re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, replace: "gh*_***" },
+    { label: "gitlab-token", re: /\bglpat-[A-Za-z0-9_-]{20,}\b/g, replace: "glpat-***" },
+    { label: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{16,}\b/g, replace: "xox*-***" },
+    { label: "npm-token", re: /\bnpm_[A-Za-z0-9]{20,}\b/g, replace: "npm_***" },
+    { label: "google-api-key", re: /\bAIza[A-Za-z0-9_-]{20,}\b/g, replace: "AIza***" },
+    { label: "stripe-live-key", re: /\b(?:sk|rk)_live_[A-Za-z0-9]{12,}\b/g, replace: "stripe-live-***" },
     { label: "aws-key", re: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, replace: "AWS-KEY-***" },
     { label: "jwt", re: /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, replace: "JWT-***" },
     {
@@ -16,6 +23,33 @@ const PATTERNS = [
         re: /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi,
         replace: "Bearer ***",
     },
+    {
+        label: "url-credential",
+        re: /(\bhttps?:\/\/[^\s/:@]+:)([^\s/@]{3,})(@)/gi,
+        replace: (_match, prefix, _value, suffix) => `${prefix}***${suffix}`,
+    },
+    {
+        // Quoted credentials may legitimately contain whitespace. Handle them before the unquoted patterns so
+        // `PASSWORD="correct horse battery staple"` is redacted as one value rather than leaking its tail.
+        label: "environment-credential",
+        re: /(\b[A-Z][A-Z0-9_]*(?:_KEY|_SECRET|_TOKEN|_PASSWORD|_PASSWD)\b\s*=\s*)(["'])([\s\S]*?)\2/g,
+        replace: (_match, prefix, quote) => `${prefix}${quote}***${quote}`,
+    },
+    {
+        label: "credential-assignment",
+        re: new RegExp(`(\\b${CREDENTIAL_NAME}\\b["']?\\s*[:=]\\s*)(["'])([\\s\\S]*?)\\2`, "gi"),
+        replace: (_match, prefix, quote) => `${prefix}${quote}***${quote}`,
+    },
+    {
+        label: "authorization",
+        re: /(\bAuthorization\s*[:=]\s*)(["'])([\s\S]*?)\2/gi,
+        replace: (_match, prefix, quote) => `${prefix}${quote}***${quote}`,
+    },
+    {
+        label: "credential-flag",
+        re: new RegExp(`(${CREDENTIAL_FLAG}(?:\\s+|=))(["'])([\\s\\S]*?)\\2`, "gi"),
+        replace: (_match, prefix, quote) => `${prefix}${quote}***${quote}`,
+    },
     {
         // Generic all-caps environment variables such as OPENAI_KEY / SOME_SERVICE_PRIVATE_KEY. Keep this
         // case-sensitive so ordinary prose/code identifiers ending in "key" are not over-redacted.
@@ -27,18 +61,18 @@ const PATTERNS = [
         // FEISHU_APP_SECRET=… · apiKey: "…" · "access_token": "…". The optional quote immediately
         // after the key handles JSON without consuming the opening quote of the value.
         label: "credential-assignment",
-        re: /(\b(?:[A-Za-z][A-Za-z0-9_.-]*(?:api[_-]?key|apikey|secret|token|password|passwd)[A-Za-z0-9_.-]*|(?:api[_-]?key|apikey|secret|token|password|passwd)[A-Za-z0-9_.-]*)\b["']?\s*[:=]\s*)(["']?)([^\s"',;}\]]{6,})(["']?)/gi,
-        replace: (_match, prefix, open, _value, close) => `${prefix}${open}***${close}`,
+        re: new RegExp(`(\\b${CREDENTIAL_NAME}\\b["']?\\s*[:=]\\s*)(?!["'])([^\\s"',;}\\]]{6,})`, "gi"),
+        replace: (_match, prefix) => `${prefix}***`,
     },
     {
         label: "authorization",
-        re: /(\bAuthorization\s*[:=]\s*)(?!Bearer\s+)(["']?)([^\s"',;}\]]{6,})(["']?)/gi,
-        replace: (_match, prefix, open, _value, close) => `${prefix}${open}***${close}`,
+        re: /(\bAuthorization\s*[:=]\s*)(?!["']|Bearer\s+)([^\s"',;}\]]{6,})/gi,
+        replace: (_match, prefix) => `${prefix}***`,
     },
     {
         label: "credential-flag",
-        re: /(--?(?:api[-_]?key|token|secret|password|passwd)(?:\s+|=))(["']?)([^\s"']{6,})(["']?)/gi,
-        replace: (_match, prefix, open, _value, close) => `${prefix}${open}***${close}`,
+        re: new RegExp(`(${CREDENTIAL_FLAG}(?:\\s+|=))(?!["'])([^\\s"']{6,})`, "gi"),
+        replace: (_match, prefix) => `${prefix}***`,
     },
 ];
 export function redactSensitiveText(text) {
@@ -53,21 +87,62 @@ export function redactSensitiveText(text) {
     }
     return { text: out, redactions };
 }
+/** Structured tool/config data often carries an opaque value that has no recognizable token prefix. In that
+ *  case the FIELD name is the evidence (`apiKey`, `access_token`, `FEISHU_APP_SECRET`, …). Keep this narrow
+ *  enough not to erase ordinary fields such as `tokenCount` or `secretary`. */
+function sensitiveFieldName(key) {
+    if (/^[A-Z][A-Z0-9_]*(?:_KEY|_SECRET|_TOKEN|_PASSWORD|_PASSWD)$/.test(key))
+        return true;
+    const compact = key.replace(/[^a-z0-9]/gi, "").toLowerCase();
+    return (compact === "authorization" ||
+        compact.endsWith("apikey") ||
+        compact.endsWith("privatekey") ||
+        compact.endsWith("token") ||
+        compact.endsWith("secret") ||
+        compact.endsWith("password") ||
+        compact.endsWith("passwd"));
+}
 /** Deep-copy a JSON-shaped value while redacting every string. Session history contains secrets not only
  *  in user text but also in assistant tool inputs and tool results, so a top-level content-only pass is
  *  insufficient. The live value is never mutated. */
 export function redactSensitiveValue(value) {
     const hits = [];
+    const seen = new WeakMap();
     const walk = (v) => {
         if (typeof v === "string") {
             const r = redactSensitiveText(v);
             hits.push(...r.redactions);
             return r.text;
         }
-        if (Array.isArray(v))
-            return v.map(walk);
+        if (Array.isArray(v)) {
+            const prior = seen.get(v);
+            if (prior)
+                return prior;
+            const out = [];
+            seen.set(v, out);
+            for (const child of v)
+                out.push(walk(child));
+            return out;
+        }
         if (v && typeof v === "object") {
-            return Object.fromEntries(Object.entries(v).map(([k, child]) => [k, walk(child)]));
+            const prior = seen.get(v);
+            if (prior)
+                return prior;
+            const out = {};
+            seen.set(v, out);
+            for (const [key, child] of Object.entries(v)) {
+                let copied;
+                if (typeof child === "string" && child && sensitiveFieldName(key)) {
+                    hits.push("credential-field");
+                    copied = "***";
+                }
+                else {
+                    copied = walk(child);
+                }
+                // defineProperty keeps an own `__proto__` data key from mutating the clone's prototype.
+                Object.defineProperty(out, key, { value: copied, enumerable: true, writable: true, configurable: true });
+            }
+            return out;
         }
         return v;
     };