@aitne/shared 0.1.0

package/dist/schemas.js

@@ -0,0 +1,271 @@
+import { z } from "zod";
+const notificationPlatformSchema = z.enum([
+    "slack",
+    "telegram",
+    "discord",
+    "whatsapp",
+]);
+// ── Context File API ──
+export const contextPutSchema = z.object({
+    content: z.string(),
+    /**
+     * Optimistic-concurrency token. When provided, the server compares this
+     * against the current file's mtime and returns 409 on mismatch. Agents
+     * can omit it (backward compatible); the dashboard always sends it to
+     * guard against lost updates.
+     */
+    expectedMtime: z.string().optional(),
+});
+/** Strict timestamp format used by SignalDetector. Lexicographic comparison
+ *  only works when both sides use zero-padded YYYY-MM-DD HH:MM:SS. */
+const CUTOFF_FORMAT_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+export const contextPatchSchema = z.object({
+    /**
+     * Target `## Section` to operate on. Required for all modes except
+     * `append_to_file`, which appends to the end of the file without
+     * targeting a section.
+     */
+    section: z.string().optional(),
+    mode: z.enum(["append", "replace", "clear", "clear_before", "append_to_file"]),
+    content: z.string().optional(),
+    /**
+     * For clear_before mode: remove entries whose `- [YYYY-MM-DD HH:MM:SS]`
+     * timestamp is ≤ this value. Entries without a parseable timestamp or
+     * with a timestamp > cutoff are preserved. This enables race-safe
+     * consumption of timestamped sections like Raw Signals.
+     */
+    cutoff: z.string().optional(),
+    /**
+     * For append mode: after appending, if the section contains more than
+     * maxEntries bullet lines (`- ...`), trim the oldest (topmost) to stay
+     * within budget. Prevents unbounded section growth.
+     */
+    maxEntries: z.number().int().positive().optional(),
+}).refine((data) => data.mode === "append_to_file" || (data.section !== undefined && data.section.length > 0), { message: "section is required for all modes except append_to_file" }).refine((data) => data.mode === "append" || data.maxEntries === undefined, { message: "maxEntries is only valid with mode 'append'" }).refine((data) => data.mode === "clear_before" || data.cutoff === undefined, { message: "cutoff is only valid with mode 'clear_before'" }).refine((data) => data.mode !== "clear_before" || (data.cutoff !== undefined && CUTOFF_FORMAT_RE.test(data.cutoff)), { message: "clear_before requires cutoff in 'YYYY-MM-DD HH:MM:SS' format (zero-padded)" });
+// ── Agent Internal API ──
+export const notifyRequestSchema = z.object({
+    message: z.string(),
+    platform: notificationPlatformSchema.optional(),
+    platforms: z.array(notificationPlatformSchema).optional(),
+    priority: z.enum(["critical", "high", "normal", "low"]).optional(),
+}).refine((data) => !(data.platform && data.platforms), { message: "Use either 'platform' or 'platforms', not both" });
+export const scheduleRequestSchema = z.object({
+    time: z.string(), // ISO8601
+    taskType: z.string(),
+    description: z
+        .string()
+        .min(20, "Description must be at least 20 characters. The wake-up agent has NO memory — the description is its only context."),
+    // Optional override for the actual task body the agent receives. When set,
+    // takes precedence over `description` as the `task` slot in the task-flow
+    // template. When omitted, `description` doubles as both the user-facing
+    // label and the agent body (preserves the long-standing skill API).
+    prompt: z
+        .string()
+        .min(20, "Prompt must be at least 20 characters. The wake-up agent has NO memory — the prompt is its only context.")
+        .optional(),
+    model: z.enum(["sonnet", "opus"]).optional(),
+    taskContext: z.record(z.string(), z.unknown()).optional(),
+});
+export const scheduleUpdateRequestSchema = z.object({
+    time: z.string().optional(),
+    description: z
+        .string()
+        .min(20, "Description must be at least 20 characters. The wake-up agent has NO memory — the description is its only context.")
+        .optional(),
+    // Pass `null` to clear an override and fall back to `description`.
+    prompt: z
+        .union([
+        z
+            .string()
+            .min(20, "Prompt must be at least 20 characters. The wake-up agent has NO memory — the prompt is its only context."),
+        z.null(),
+    ])
+        .optional(),
+    message: z.string().min(1).optional(), // for dm type only
+    model: z.enum(["sonnet", "opus"]).optional(),
+    taskContext: z.record(z.string(), z.unknown()).optional(),
+}).refine((data) => Object.values(data).some((v) => v !== undefined), { message: "At least one field must be provided for update" }).refine((data) => !(data.description !== undefined && data.message !== undefined), { message: "Cannot set both 'description' and 'message'. Use 'description' for wake-up tasks, 'message' for dm." }).refine(
+// dm rows do not run an agent, so a prompt override has nothing to
+// override. This catches the cross-type combo at validation time
+// (the route handler also rejects prompt on dm-type rows for the
+// single-field case where the row's task_type is the gate).
+(data) => !(data.prompt !== undefined && data.message !== undefined), { message: "Cannot set both 'prompt' and 'message'. 'prompt' is only valid for non-dm schedules." });
+export const scheduleDmRequestSchema = z.object({
+    time: z.string(), // ISO8601 with timezone
+    message: z.string().min(1, "Message cannot be empty"),
+    platform: notificationPlatformSchema.optional(), // temporary singular form
+    platforms: z.array(notificationPlatformSchema).optional(),
+    importance: z.enum(["transient", "normal", "strategic"]).optional(),
+}).refine((data) => !(data.platform && data.platforms), { message: "Use either 'platform' or 'platforms', not both" });
+export const actionLogRequestSchema = z.object({
+    actionType: z.string(),
+    detail: z.string(),
+    result: z.enum(["success", "failed", "partial", "skipped"]),
+});
+// ── User Skills API ──
+/**
+ * Skill slug constraints — kebab-case, 1-64 chars, safe for filesystem & URLs.
+ * Explicitly rejects path traversal, whitespace, and uppercase to keep
+ * filesystem semantics consistent across macOS (case-insensitive) and Linux.
+ */
+export const skillNameSchema = z
+    .string()
+    .min(1, "Skill name cannot be empty")
+    .max(64, "Skill name must be at most 64 characters")
+    .regex(/^[a-z0-9][a-z0-9-]*$/, "Skill name must be kebab-case (lowercase letters, digits, hyphens) and start with a letter or digit");
+/**
+ * Single-line description constraint.
+ *
+ * The SKILL.md frontmatter serializer writes descriptions inline as a
+ * double-quoted YAML scalar. Multi-line descriptions would break the
+ * minimal regex-based parser we use, so we reject newlines at the
+ * validation layer rather than implementing a full YAML block scalar.
+ */
+const skillDescriptionSchema = z
+    .string()
+    .min(1, "description is required")
+    .max(500, "description must be at most 500 characters")
+    .refine((v) => !/[\r\n]/.test(v), {
+    message: "description cannot contain newlines",
+});
+/**
+ * `allowed-tools` constraint — matches Claude Code's official SKILL.md
+ * convention (e.g. `Bash(curl *)`, `Read`, `Grep`). Each entry is a single
+ * line with no control characters.
+ */
+const skillAllowedToolsSchema = z
+    .array(z
+    .string()
+    .min(1)
+    .max(200)
+    .refine((v) => !/[\r\n]/.test(v), {
+    message: "tool entries cannot contain newlines",
+}))
+    .max(32, "at most 32 allowed-tools entries");
+export const skillCreateSchema = z.object({
+    name: skillNameSchema,
+    description: skillDescriptionSchema,
+    content: z.string().min(1, "content cannot be empty"),
+    allowedTools: skillAllowedToolsSchema.optional(),
+});
+export const skillUpdateSchema = z.object({
+    description: skillDescriptionSchema.optional(),
+    content: z.string().min(1, "content cannot be empty").optional(),
+    allowedTools: skillAllowedToolsSchema.optional(),
+}).refine((data) => data.description !== undefined ||
+    data.content !== undefined ||
+    data.allowedTools !== undefined, { message: "At least one of 'description', 'content', or 'allowedTools' must be provided" });
+// The schemas are consumed only as the source of the `z.infer<typeof ...>`
+// types exported below; the Zod values are never called at runtime. Prefix
+// with `_` so ESLint's no-unused-vars stops flagging the binding.
+const _skillSummarySchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    builtin: z.boolean(),
+    updatedAt: z.string(),
+});
+const _skillDetailSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    content: z.string(),
+    allowedTools: z.array(z.string()),
+    builtin: z.boolean(),
+    updatedAt: z.string(),
+});
+// ── Calendar API ──
+const calendarEventFields = {
+    description: z.string().max(10_000).optional(),
+    location: z.string().max(1000).optional(),
+    reminders: z.object({
+        useDefault: z.boolean(),
+        overrides: z.array(z.object({
+            method: z.enum(["email", "popup"]),
+            minutes: z.number().int().min(0).max(40320),
+        })).max(5).optional(),
+    }).optional(),
+    recurrence: z.array(z.string().max(500)).max(5).optional(),
+    attendees: z.array(z.object({
+        email: z.string().email(),
+    })).max(100).optional(),
+    visibility: z.enum(["default", "public", "private", "confidential"]).optional(),
+};
+export const calendarCreateEventSchema = z.object({
+    summary: z.string().min(1).max(1000),
+    start: z.string().min(1),
+    end: z.string().min(1),
+    ...calendarEventFields,
+});
+export const calendarUpdateEventSchema = z.object({
+    summary: z.string().min(1).max(1000).optional(),
+    start: z.string().min(1).optional(),
+    end: z.string().min(1).optional(),
+    ...calendarEventFields,
+}).refine((data) => Object.values(data).some((v) => v !== undefined), { message: "At least one field must be provided for update" });
+export const calendarFreeBusySchema = z.object({
+    timeMin: z.string().min(1),
+    timeMax: z.string().min(1),
+    calendarIds: z.array(z.string()).min(1).max(50).optional(),
+});
+// ── Recurring Schedules ──
+const HH_MM_RE = /^\d{2}:\d{2}$/;
+export const recurrenceRuleSchema = z.object({
+    frequency: z.enum(["daily", "weekly", "monthly"]),
+    /** HH:MM local time */
+    time: z.string().regex(HH_MM_RE, "time must be HH:MM format"),
+    /** IANA timezone (e.g. "America/New_York"). Optional — auto-filled from daemon config when omitted. */
+    timezone: z.string().min(1).optional(),
+    /** 0=Sun..6=Sat — required when frequency is weekly */
+    daysOfWeek: z.array(z.number().int().min(0).max(6)).min(1).max(7).optional(),
+    /** 1-31 — required when frequency is monthly. 29-31 clamp to last day of short months */
+    daysOfMonth: z.array(z.number().int().min(1).max(31)).min(1).max(31).optional(),
+}).refine((data) => data.frequency !== "weekly" || (data.daysOfWeek !== undefined && data.daysOfWeek.length > 0), { message: "daysOfWeek is required for weekly frequency" }).refine((data) => data.frequency !== "monthly" || (data.daysOfMonth !== undefined && data.daysOfMonth.length > 0), { message: "daysOfMonth is required for monthly frequency" }).refine((data) => data.frequency !== "daily" || data.daysOfWeek === undefined, { message: "daysOfWeek is not allowed for daily frequency" }).refine((data) => data.frequency !== "daily" || data.daysOfMonth === undefined, { message: "daysOfMonth is not allowed for daily frequency" }).refine((data) => data.frequency !== "weekly" || data.daysOfMonth === undefined, { message: "daysOfMonth is not allowed for weekly frequency" }).refine((data) => data.frequency !== "monthly" || data.daysOfWeek === undefined, { message: "daysOfWeek is not allowed for monthly frequency" });
+export const recurringScheduleCreateSchema = z.object({
+    taskType: z.string().min(1),
+    description: z.string().min(20, "Description must be at least 20 characters. The wake-up agent has NO memory — the description is its only context."),
+    // Optional override for the agent task body. See scheduleRequestSchema.prompt.
+    prompt: z
+        .string()
+        .min(20, "Prompt must be at least 20 characters. The wake-up agent has NO memory — the prompt is its only context.")
+        .optional(),
+    recurrenceRule: recurrenceRuleSchema,
+    model: z.enum(["sonnet", "opus"]).optional(),
+    taskContext: z.record(z.string(), z.unknown()).optional(),
+});
+export const recurringScheduleUpdateSchema = z.object({
+    description: z.string().min(20, "Description must be at least 20 characters.").optional(),
+    // Pass `null` to clear an override and fall back to `description`.
+    prompt: z
+        .union([
+        z.string().min(20, "Prompt must be at least 20 characters."),
+        z.null(),
+    ])
+        .optional(),
+    recurrenceRule: recurrenceRuleSchema.optional(),
+    model: z.enum(["sonnet", "opus"]).optional(),
+    taskContext: z.record(z.string(), z.unknown()).optional(),
+    enabled: z.boolean().optional(),
+}).refine((data) => Object.values(data).some((v) => v !== undefined), { message: "At least one field must be provided for update" });
+// ── Automation Triggers (docs/design/19-dashboard-ia-and-triggers.md) ──
+const HH_MM_RE_TRIGGER = /^([01]\d|2[0-3]):[0-5]\d$/;
+const triggerDomainSchema = z.enum(["git"]);
+const triggerEventTypeSchema = z.enum(["cron.daily", "cron.weekly"]);
+export const triggerCreateSchema = z.object({
+    domain: triggerDomainSchema,
+    eventType: triggerEventTypeSchema,
+    prompt: z
+        .string()
+        .min(20, "Prompt must be at least 20 characters. The trigger run starts with no chat memory — the prompt is its only instruction."),
+    time: z.string().regex(HH_MM_RE_TRIGGER, "time must be HH:MM format"),
+    daysOfWeek: z.array(z.number().int().min(0).max(6)).min(1).max(7).optional(),
+}).refine((data) => data.eventType !== "cron.weekly" ||
+    (data.daysOfWeek !== undefined && data.daysOfWeek.length > 0), { message: "daysOfWeek is required for cron.weekly" });
+export const triggerUpdateSchema = z.object({
+    prompt: z
+        .string()
+        .min(20, "Prompt must be at least 20 characters.")
+        .optional(),
+    enabled: z.boolean().optional(),
+    time: z.string().regex(HH_MM_RE_TRIGGER, "time must be HH:MM format").optional(),
+    daysOfWeek: z.array(z.number().int().min(0).max(6)).min(1).max(7).optional(),
+}).refine((data) => Object.values(data).some((v) => v !== undefined), { message: "At least one field must be provided for update" });
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

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

package/dist/secret-client-factory.d.ts

@@ -0,0 +1,16 @@
+import type { PersonalAgentKeychainClient } from "./keychain-helper-client.js";
+/**
+ * Create a platform-appropriate secret client.
+ *
+ * Resolution order:
+ * - macOS  → NativePersonalAgentKeychainClient (macOS Keychain)
+ * - win32  → WindowsDpapiSecretClient (DPAPI)
+ * - linux  → WSL? FileSecretClient : secret-tool available? LinuxSecretClient : FileSecretClient
+ * - other  → FileSecretClient
+ *
+ * The FileSecretClient fallback requires a master password from
+ * `PA_MASTER_PASSWORD` env or `~/.personal-agent/secrets/.master-key` file.
+ * If neither is available, throws with setup instructions.
+ */
+export declare function createSecretClient(): Promise<PersonalAgentKeychainClient>;
+//# sourceMappingURL=secret-client-factory.d.ts.map

package/dist/secret-client-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-client-factory.d.ts","sourceRoot":"","sources":["../src/secret-client-factory.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,2BAA2B,CAAC,CAwC/E"}

package/dist/secret-client-factory.js

@@ -0,0 +1,111 @@
+import { platform } from "node:os";
+import { readFileSync, accessSync, constants } from "node:fs";
+import { join, delimiter } from "node:path";
+/**
+ * Create a platform-appropriate secret client.
+ *
+ * Resolution order:
+ * - macOS  → NativePersonalAgentKeychainClient (macOS Keychain)
+ * - win32  → WindowsDpapiSecretClient (DPAPI)
+ * - linux  → WSL? FileSecretClient : secret-tool available? LinuxSecretClient : FileSecretClient
+ * - other  → FileSecretClient
+ *
+ * The FileSecretClient fallback requires a master password from
+ * `PA_MASTER_PASSWORD` env or `~/.personal-agent/secrets/.master-key` file.
+ * If neither is available, throws with setup instructions.
+ */
+export async function createSecretClient() {
+    const os = platform();
+    switch (os) {
+        case "darwin": {
+            const { NativePersonalAgentKeychainClient } = await import("./keychain-helper-client.js");
+            return new NativePersonalAgentKeychainClient();
+        }
+        case "win32": {
+            const { WindowsDpapiSecretClient } = await import("./secret-client-windows.js");
+            // Resolve the PowerShell binary once at startup. Windows PowerShell
+            // 5.1 (`powershell.exe`) is preferred because it's the in-box choice
+            // on every modern desktop SKU; PowerShell 7+ (`pwsh.exe`) is the
+            // fallback for setups that ship pwsh-only (Windows Server Core,
+            // PowerShell-Core-only installs). If neither is on PATH, leave the
+            // default in place — the first DPAPI exec will surface a clear
+            // ENOENT and the caller can install one.
+            const psBinary = findExecutableInPath("powershell.exe")
+                ? "powershell.exe"
+                : findExecutableInPath("pwsh.exe")
+                    ? "pwsh.exe"
+                    : "powershell.exe";
+            return new WindowsDpapiSecretClient(undefined, psBinary);
+        }
+        case "linux": {
+            if (isWsl()) {
+                return createFileClient();
+            }
+            if (findExecutableInPath("secret-tool")) {
+                const { LinuxSecretClient } = await import("./secret-client-linux.js");
+                return new LinuxSecretClient();
+            }
+            return createFileClient();
+        }
+        default:
+            return createFileClient();
+    }
+}
+async function createFileClient() {
+    const { FileSecretClient, resolveMasterPassword } = await import("./secret-client-file.js");
+    const password = resolveMasterPassword();
+    if (!password) {
+        throw new Error("No master password configured for the encrypted secret store. " +
+            "Set PA_MASTER_PASSWORD environment variable or create " +
+            "~/.personal-agent/secrets/.master-key file.");
+    }
+    return await FileSecretClient.create(password);
+}
+/**
+ * Detect Windows Subsystem for Linux.
+ * WSL reports `process.platform === "linux"` but cannot use `secret-tool`
+ * because D-Bus / GNOME Keyring are typically unavailable.
+ *
+ * The platform check is intentionally redundant with the `case "linux"`
+ * caller above: `/proc/version` only exists on Linux, so calling this
+ * helper from a darwin/win32 path would crash in the read. Keeping the
+ * guard inline makes this safe to call from any future code site.
+ */
+function isWsl() {
+    if (platform() !== "linux")
+        return false;
+    try {
+        const version = readFileSync("/proc/version", "utf-8");
+        return /microsoft|wsl/i.test(version);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Lightweight executable finder (shared package cannot depend on daemon's cli-utils).
+ * Checks PATH for the given command, respecting PATHEXT on Windows.
+ */
+function findExecutableInPath(command) {
+    const pathValue = process.env.PATH;
+    if (!pathValue)
+        return false;
+    const extensions = platform() === "win32" && !/\.[A-Za-z0-9]+$/.test(command)
+        ? (process.env.PATHEXT?.split(";").filter(Boolean) ?? [".exe", ".cmd", ".bat"])
+        : [""];
+    for (const dir of pathValue.split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of extensions) {
+            try {
+                accessSync(join(dir, `${command}${ext}`), constants.X_OK);
+                return true;
+            }
+            catch {
+                // keep scanning
+            }
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=secret-client-factory.js.map

package/dist/secret-client-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-client-factory.js","sourceRoot":"","sources":["../src/secret-client-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG5C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC;IAEtB,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,EAAE,iCAAiC,EAAE,GAAG,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC;YAC1F,OAAO,IAAI,iCAAiC,EAAE,CAAC;QACjD,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,EAAE,wBAAwB,EAAE,GAAG,MAAM,MAAM,CAAC,4BAA4B,CAAC,CAAC;YAChF,oEAAoE;YACpE,qEAAqE;YACrE,iEAAiE;YACjE,gEAAgE;YAChE,mEAAmE;YACnE,+DAA+D;YAC/D,yCAAyC;YACzC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,gBAAgB,CAAC;gBACrD,CAAC,CAAC,gBAAgB;gBAClB,CAAC,CAAC,oBAAoB,CAAC,UAAU,CAAC;oBAChC,CAAC,CAAC,UAAU;oBACZ,CAAC,CAAC,gBAAgB,CAAC;YACvB,OAAO,IAAI,wBAAwB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC3D,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,IAAI,KAAK,EAAE,EAAE,CAAC;gBACZ,OAAO,gBAAgB,EAAE,CAAC;YAC5B,CAAC;YACD,IAAI,oBAAoB,CAAC,aAAa,CAAC,EAAE,CAAC;gBACxC,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;gBACvE,OAAO,IAAI,iBAAiB,EAAE,CAAC;YACjC,CAAC;YACD,OAAO,gBAAgB,EAAE,CAAC;QAC5B,CAAC;QAED;YACE,OAAO,gBAAgB,EAAE,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,KAAK,UAAU,gBAAgB;IAC7B,MAAM,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;IAC5F,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;IACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,gEAAgE;YAChE,wDAAwD;YACxD,6CAA6C,CAC9C,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,KAAK;IACZ,IAAI,QAAQ,EAAE,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,OAAe;IAC3C,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;IACnC,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAE7B,MAAM,UAAU,GAAG,QAAQ,EAAE,KAAK,OAAO,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC;QAC3E,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/E,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAET,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACH,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,GAAG,EAAE,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;gBAC1D,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,gBAAgB;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/secret-client-file.d.ts

@@ -0,0 +1,51 @@
+import type { PersonalAgentKeychainClient } from "./keychain-helper-client.js";
+/**
+ * Encrypted file-based secret client.
+ *
+ * Used as the universal fallback when no native secret store is available
+ * (headless Linux, WSL, or any unsupported platform).
+ *
+ * Each secret is stored in its own `.enc` file under `~/.personal-agent/secrets/`,
+ * encrypted with AES-256-GCM. The encryption key is derived from a master
+ * password using async scrypt with a per-secret random salt.
+ *
+ * Use the static `create()` factory to construct — it validates the master
+ * password asynchronously before returning the instance.
+ *
+ * The master password is resolved by callers (typically the factory) from:
+ *   1. `PA_MASTER_PASSWORD` environment variable
+ *   2. `~/.personal-agent/secrets/.master-key` file (chmod 0600)
+ *
+ * On first use, the master password hash is stored in `.master-hash` for
+ * validation on subsequent accesses.
+ */
+export declare class FileSecretClient implements PersonalAgentKeychainClient {
+    private readonly secretsDir;
+    private readonly masterPassword;
+    /**
+     * Create and initialize a FileSecretClient.
+     * Validates the master password against the stored hash (or creates one).
+     */
+    static create(masterPassword: string, secretsDir?: string): Promise<FileSecretClient>;
+    /** @internal Use `FileSecretClient.create()` instead. */
+    constructor(masterPassword: string, secretsDir?: string);
+    private filePath;
+    private masterHashPath;
+    private deriveKey;
+    /**
+     * On first use, store a hash of the master password so we can detect
+     * mismatches on subsequent accesses. If the hash file already exists,
+     * validate against it and throw on mismatch.
+     */
+    private ensureMasterHash;
+    has(secretName: string): Promise<boolean>;
+    get(secretName: string): Promise<string | null>;
+    set(secretName: string, value: string): Promise<void>;
+    delete(secretName: string): Promise<void>;
+}
+/**
+ * Resolve master password from environment variable or key file.
+ * Returns null if neither source provides a password.
+ */
+export declare function resolveMasterPassword(secretsDir?: string): string | null;
+//# sourceMappingURL=secret-client-file.d.ts.map

package/dist/secret-client-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-client-file.d.ts","sourceRoot":"","sources":["../src/secret-client-file.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAkD/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,gBAAiB,YAAW,2BAA2B;IAClE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC;;;OAGG;WACU,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAM3F,yDAAyD;gBAC7C,cAAc,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;IAMvD,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,cAAc;YAIR,SAAS;IAQvB;;;;OAIG;YACW,gBAAgB;IAuBxB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIzC,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkB/C,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBrD,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIhD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAuBf"}

package/dist/secret-client-file.js

@@ -0,0 +1,160 @@
+import { createCipheriv, createDecipheriv, randomBytes, scrypt, timingSafeEqual, } from "node:crypto";
+import { promisify } from "node:util";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+// promisify(scrypt) accepts (password, salt, keylen, options?) but TS only
+// types the 3-arg overload. Cast to the correct signature.
+const scryptAsync = promisify(scrypt);
+const ALGORITHM = "aes-256-gcm";
+const KEY_LENGTH = 32; // 256 bits
+const IV_LENGTH = 12; // 96 bits for GCM
+const FILE_MODE = 0o600; // owner-only read/write
+const SALT_LENGTH = 32; // 256 bits
+const SCRYPT_COST = 16384; // N=2^14, balances speed vs. security for local use
+const SCRYPT_BLOCK_SIZE = 8;
+const SCRYPT_PARALLELIZATION = 1;
+/**
+ * Encrypted file-based secret client.
+ *
+ * Used as the universal fallback when no native secret store is available
+ * (headless Linux, WSL, or any unsupported platform).
+ *
+ * Each secret is stored in its own `.enc` file under `~/.personal-agent/secrets/`,
+ * encrypted with AES-256-GCM. The encryption key is derived from a master
+ * password using async scrypt with a per-secret random salt.
+ *
+ * Use the static `create()` factory to construct — it validates the master
+ * password asynchronously before returning the instance.
+ *
+ * The master password is resolved by callers (typically the factory) from:
+ *   1. `PA_MASTER_PASSWORD` environment variable
+ *   2. `~/.personal-agent/secrets/.master-key` file (chmod 0600)
+ *
+ * On first use, the master password hash is stored in `.master-hash` for
+ * validation on subsequent accesses.
+ */
+export class FileSecretClient {
+    secretsDir;
+    masterPassword;
+    /**
+     * Create and initialize a FileSecretClient.
+     * Validates the master password against the stored hash (or creates one).
+     */
+    static async create(masterPassword, secretsDir) {
+        const client = new FileSecretClient(masterPassword, secretsDir);
+        await client.ensureMasterHash();
+        return client;
+    }
+    /** @internal Use `FileSecretClient.create()` instead. */
+    constructor(masterPassword, secretsDir) {
+        this.masterPassword = masterPassword;
+        this.secretsDir = secretsDir ?? join(homedir(), ".personal-agent", "secrets");
+        mkdirSync(this.secretsDir, { recursive: true });
+    }
+    filePath(secretName) {
+        if (/[/\\]/.test(secretName)) {
+            throw new Error(`Invalid secret name: ${secretName}`);
+        }
+        return join(this.secretsDir, `${secretName}.enc`);
+    }
+    masterHashPath() {
+        return join(this.secretsDir, ".master-hash");
+    }
+    async deriveKey(salt) {
+        return await scryptAsync(this.masterPassword, salt, KEY_LENGTH, {
+            N: SCRYPT_COST,
+            r: SCRYPT_BLOCK_SIZE,
+            p: SCRYPT_PARALLELIZATION,
+        });
+    }
+    /**
+     * On first use, store a hash of the master password so we can detect
+     * mismatches on subsequent accesses. If the hash file already exists,
+     * validate against it and throw on mismatch.
+     */
+    async ensureMasterHash() {
+        const hashPath = this.masterHashPath();
+        if (existsSync(hashPath)) {
+            const stored = JSON.parse(readFileSync(hashPath, "utf-8"));
+            const salt = Buffer.from(stored.salt, "hex");
+            const derived = await this.deriveKey(salt);
+            const expected = Buffer.from(stored.hash, "hex");
+            if (!timingSafeEqual(derived, expected)) {
+                throw new Error("Master password mismatch. The password does not match the one used to create the secret store.");
+            }
+        }
+        else {
+            const salt = randomBytes(SALT_LENGTH);
+            const hash = await this.deriveKey(salt);
+            const content = {
+                salt: salt.toString("hex"),
+                hash: hash.toString("hex"),
+            };
+            writeFileSync(hashPath, JSON.stringify(content), { encoding: "utf-8", mode: FILE_MODE });
+        }
+    }
+    async has(secretName) {
+        return existsSync(this.filePath(secretName));
+    }
+    async get(secretName) {
+        const path = this.filePath(secretName);
+        if (!existsSync(path))
+            return null;
+        const stored = JSON.parse(readFileSync(path, "utf-8"));
+        const salt = Buffer.from(stored.salt, "hex");
+        const iv = Buffer.from(stored.iv, "hex");
+        const authTag = Buffer.from(stored.authTag, "hex");
+        const ciphertext = Buffer.from(stored.ciphertext, "hex");
+        const key = await this.deriveKey(salt);
+        const decipher = createDecipheriv(ALGORITHM, key, iv);
+        decipher.setAuthTag(authTag);
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return decrypted.toString("utf-8");
+    }
+    async set(secretName, value) {
+        const salt = randomBytes(SALT_LENGTH);
+        const iv = randomBytes(IV_LENGTH);
+        const key = await this.deriveKey(salt);
+        const cipher = createCipheriv(ALGORITHM, key, iv);
+        const encrypted = Buffer.concat([cipher.update(value, "utf-8"), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        const content = {
+            salt: salt.toString("hex"),
+            iv: iv.toString("hex"),
+            authTag: authTag.toString("hex"),
+            ciphertext: encrypted.toString("hex"),
+        };
+        writeFileSync(this.filePath(secretName), JSON.stringify(content), { encoding: "utf-8", mode: FILE_MODE });
+    }
+    async delete(secretName) {
+        const path = this.filePath(secretName);
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+}
+/**
+ * Resolve master password from environment variable or key file.
+ * Returns null if neither source provides a password.
+ */
+export function resolveMasterPassword(secretsDir) {
+    // 1. Environment variable takes precedence
+    if (process.env.PA_MASTER_PASSWORD) {
+        return process.env.PA_MASTER_PASSWORD;
+    }
+    // 2. Key file fallback
+    const dir = secretsDir ?? join(homedir(), ".personal-agent", "secrets");
+    const keyFilePath = join(dir, ".master-key");
+    if (existsSync(keyFilePath)) {
+        // Validate permissions — .master-key must be owner-only (0600 or 0400).
+        // Other modes risk exposing the master password to same-machine users.
+        const mode = statSync(keyFilePath).mode & 0o777;
+        if (mode !== 0o600 && mode !== 0o400) {
+            throw new Error(`.master-key has permissions 0${mode.toString(8)}, expected 0600 or 0400. ` +
+                `Fix with: chmod 600 ${keyFilePath}`);
+        }
+        return readFileSync(keyFilePath, "utf-8").trim();
+    }
+    return null;
+}
+//# sourceMappingURL=secret-client-file.js.map