@dawn-ai/permissions 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Brian Love
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { matchPermission } from "./pattern-matching.js";
+export { createPermissionsStore } from "./permissions-store.js";
+export { suggestedCommandPattern, suggestedPathPattern } from "./suggested-pattern.js";
+export type { CommandDetail, PathDetail, PermissionDecision, PermissionMode, PermissionRequest, PermissionsFile, PermissionsStore, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AACtF,YAAY,EACV,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { matchPermission } from "./pattern-matching.js";
+export { createPermissionsStore } from "./permissions-store.js";
+export { suggestedCommandPattern, suggestedPathPattern } from "./suggested-pattern.js";

package/dist/pattern-matching.d.ts

@@ -0,0 +1,12 @@
+type PatternMap = Readonly<Record<string, readonly string[]>>;
+/**
+ * Match a tool+candidate against allow + deny pattern maps.
+ *
+ * Semantics:
+ *   - deny wins over allow
+ *   - prefix matching: `candidate.startsWith(pattern)`
+ *   - no entries for tool → "unknown"
+ */
+export declare function matchPermission(tool: string, candidate: string, allow: PatternMap, deny: PatternMap): "allow" | "deny" | "unknown";
+export {};
+//# sourceMappingURL=pattern-matching.d.ts.map

package/dist/pattern-matching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-matching.d.ts","sourceRoot":"","sources":["../src/pattern-matching.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;AAE7D;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,UAAU,GACf,OAAO,GAAG,MAAM,GAAG,SAAS,CAU9B"}

package/dist/pattern-matching.js

@@ -0,0 +1,21 @@
+/**
+ * Match a tool+candidate against allow + deny pattern maps.
+ *
+ * Semantics:
+ *   - deny wins over allow
+ *   - prefix matching: `candidate.startsWith(pattern)`
+ *   - no entries for tool → "unknown"
+ */
+export function matchPermission(tool, candidate, allow, deny) {
+    const denyList = deny[tool] ?? [];
+    for (const pattern of denyList) {
+        if (candidate.startsWith(pattern))
+            return "deny";
+    }
+    const allowList = allow[tool] ?? [];
+    for (const pattern of allowList) {
+        if (candidate.startsWith(pattern))
+            return "allow";
+    }
+    return "unknown";
+}

package/dist/permissions-store.d.ts

@@ -0,0 +1,9 @@
+import type { PermissionMode, PermissionsFile, PermissionsStore } from "./types.js";
+interface CreateOptions {
+    readonly appRoot: string;
+    readonly config: PermissionsFile | undefined;
+    readonly mode: PermissionMode;
+}
+export declare function createPermissionsStore(opts: CreateOptions): PermissionsStore;
+export {};
+//# sourceMappingURL=permissions-store.d.ts.map

package/dist/permissions-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-store.d.ts","sourceRoot":"","sources":["../src/permissions-store.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAKnF,UAAU,aAAa;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAC9B;AA6CD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,aAAa,GAAG,gBAAgB,CAsF5E"}

package/dist/permissions-store.js

@@ -0,0 +1,125 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { matchPermission } from "./pattern-matching.js";
+const PERMISSIONS_DIR = ".dawn";
+const PERMISSIONS_FILE = "permissions.json";
+function emptyState() {
+    return { configAllow: {}, configDeny: {}, runtimeAllow: {}, runtimeDeny: {} };
+}
+function cloneMap(src) {
+    const out = {};
+    for (const [k, v] of Object.entries(src))
+        out[k] = [...v];
+    return out;
+}
+function effectiveAllow(state, mode) {
+    if (mode === "bypass")
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(state.configAllow))
+        out[k] = [...v];
+    if (mode === "interactive") {
+        for (const [k, v] of Object.entries(state.runtimeAllow)) {
+            out[k] = [...(out[k] ?? []), ...v];
+        }
+    }
+    return out;
+}
+function effectiveDeny(state, mode) {
+    if (mode === "bypass")
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(state.configDeny))
+        out[k] = [...v];
+    if (mode === "interactive") {
+        for (const [k, v] of Object.entries(state.runtimeDeny)) {
+            out[k] = [...(out[k] ?? []), ...v];
+        }
+    }
+    return out;
+}
+export function createPermissionsStore(opts) {
+    const { appRoot, config, mode } = opts;
+    const state = emptyState();
+    if (config) {
+        state.configAllow = cloneMap(config.allow);
+        state.configDeny = cloneMap(config.deny);
+    }
+    let writeQueue = Promise.resolve();
+    async function loadRuntimeFile() {
+        const filePath = join(appRoot, PERMISSIONS_DIR, PERMISSIONS_FILE);
+        if (!existsSync(filePath))
+            return;
+        let raw;
+        try {
+            raw = await readFile(filePath, "utf8");
+        }
+        catch (err) {
+            throw new Error(`Failed to read permissions.json: ${err.message}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`Malformed permissions.json: ${err.message}`);
+        }
+        const p = parsed;
+        if (p.allow && typeof p.allow === "object") {
+            state.runtimeAllow = cloneMap(p.allow);
+        }
+        if (p.deny && typeof p.deny === "object") {
+            state.runtimeDeny = cloneMap(p.deny);
+        }
+    }
+    async function persistRuntimeFile() {
+        const dir = join(appRoot, PERMISSIONS_DIR);
+        await mkdir(dir, { recursive: true });
+        const file = {
+            version: 1,
+            allow: state.runtimeAllow,
+            deny: state.runtimeDeny,
+        };
+        await writeFile(join(dir, PERMISSIONS_FILE), `${JSON.stringify(file, null, 2)}\n`, "utf8");
+    }
+    async function ensureGitignoreEntry() {
+        const gitignorePath = join(appRoot, ".gitignore");
+        let content = "";
+        if (existsSync(gitignorePath)) {
+            content = await readFile(gitignorePath, "utf8");
+            if (content.split("\n").some((line) => line.trim() === ".dawn/"))
+                return;
+            if (!content.endsWith("\n") && content.length > 0)
+                content += "\n";
+            content += ".dawn/\n";
+        }
+        else {
+            content = ".dawn/\n";
+        }
+        await writeFile(gitignorePath, content, "utf8");
+    }
+    return {
+        mode,
+        match(tool, candidate) {
+            return matchPermission(tool, candidate, effectiveAllow(state, mode), effectiveDeny(state, mode));
+        },
+        async load() {
+            if (mode === "interactive") {
+                await loadRuntimeFile();
+            }
+        },
+        async addAllow(tool, pattern) {
+            const job = async () => {
+                const list = state.runtimeAllow[tool] ?? [];
+                if (!list.includes(pattern))
+                    list.push(pattern);
+                state.runtimeAllow[tool] = list;
+                await persistRuntimeFile();
+                await ensureGitignoreEntry();
+            };
+            writeQueue = writeQueue.then(job, job);
+            await writeQueue;
+        },
+    };
+}

package/dist/suggested-pattern.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Default suggested pattern for a shell command.
+ * Returns the first two whitespace-separated tokens.
+ */
+export declare function suggestedCommandPattern(command: string): string;
+/**
+ * Default suggested pattern for a filesystem path.
+ * Returns the parent directory with trailing slash.
+ */
+export declare function suggestedPathPattern(path: string): string;
+//# sourceMappingURL=suggested-pattern.d.ts.map

package/dist/suggested-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggested-pattern.d.ts","sourceRoot":"","sources":["../src/suggested-pattern.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIzD"}

package/dist/suggested-pattern.js

@@ -0,0 +1,22 @@
+import { dirname } from "node:path";
+/**
+ * Default suggested pattern for a shell command.
+ * Returns the first two whitespace-separated tokens.
+ */
+export function suggestedCommandPattern(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return "";
+    const tokens = trimmed.split(/\s+/);
+    return tokens.slice(0, 2).join(" ");
+}
+/**
+ * Default suggested pattern for a filesystem path.
+ * Returns the parent directory with trailing slash.
+ */
+export function suggestedPathPattern(path) {
+    if (path.endsWith("/"))
+        return path;
+    const parent = dirname(path);
+    return parent === "/" ? "/" : `${parent}/`;
+}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Public types for the Dawn HITL permissions system.
+ *
+ * The workspace capability calls into a `PermissionsStore` before
+ * invoking its filesystem/exec backends. The store consults the
+ * runtime file at .dawn/permissions.json plus the config-seeded
+ * allow/deny lists and returns one of three decisions: "allow",
+ * "deny", or "unknown". On "unknown" in interactive mode the
+ * capability emits LangGraph's `interrupt()` with a `PermissionRequest`
+ * payload; the resume mechanism returns a `PermissionDecision`.
+ */
+export type PermissionMode = "interactive" | "non-interactive" | "bypass";
+export type PermissionDecision = "once" | "always" | "deny";
+export interface PermissionsFile {
+    readonly version: 1;
+    readonly allow: Readonly<Record<string, readonly string[]>>;
+    readonly deny: Readonly<Record<string, readonly string[]>>;
+}
+export interface CommandDetail {
+    readonly command: string;
+    readonly suggestedPattern: string;
+}
+export interface PathDetail {
+    readonly path: string;
+    readonly operation: "readFile" | "writeFile" | "listDir";
+    readonly suggestedPattern: string;
+}
+export interface PermissionRequest {
+    readonly interruptId: string;
+    readonly kind: "command" | "path";
+    readonly detail: CommandDetail | PathDetail;
+    readonly threadId: string;
+    readonly callId?: string;
+}
+export interface PermissionsStore {
+    /** Loaded once at construction; subsequent loads not exposed in v1. */
+    load(): Promise<void>;
+    match(tool: string, candidate: string): "allow" | "deny" | "unknown";
+    /** Persists an allow entry to disk and updates the in-memory cache. */
+    addAllow(tool: string, pattern: string): Promise<void>;
+    /** Active mode (resolved from config + env at construction). */
+    readonly mode: PermissionMode;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,iBAAiB,GAAG,QAAQ,CAAA;AAEzE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;IAC3D,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;CAC3D;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAAA;IACxD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAAA;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;IACpE,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAC9B"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Public types for the Dawn HITL permissions system.
+ *
+ * The workspace capability calls into a `PermissionsStore` before
+ * invoking its filesystem/exec backends. The store consults the
+ * runtime file at .dawn/permissions.json plus the config-seeded
+ * allow/deny lists and returns one of three decisions: "allow",
+ * "deny", or "unknown". On "unknown" in interactive mode the
+ * capability emits LangGraph's `interrupt()` with a `PermissionRequest`
+ * payload; the resume mechanism returns a `PermissionDecision`.
+ */
+export {};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dawn-ai/permissions",
+  "version": "0.1.8",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/cacheplane/dawnai/tree/main/packages/permissions#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cacheplane/dawnai.git",
+    "directory": "packages/permissions"
+  },
+  "bugs": {
+    "url": "https://github.com/cacheplane/dawnai/issues"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "@dawn-ai/config-typescript": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "lint": "biome check --config-path ../config-biome/biome.json package.json src tsconfig.json vitest.config.ts",
+    "test": "vitest --run --config vitest.config.ts --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}