safe-notion 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# notion-cli-for-ai
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run src/index.ts
+```
+
+This project was created using `bun init` in bun v1.3.3. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/config.sample.jsonc

@@ -0,0 +1,77 @@
+{
+  // Notion Safe CLI - Configuration
+  // Rules are evaluated in order; first matching rule applies
+  //
+  // Permission types (granular format):
+  //   page:read, page:update, page:create
+  //   database:read, database:query, database:create
+  //   block:read, block:append, block:delete
+  "rules": [
+    {
+      // Example 1: Read-only access to a specific page and all its children
+      "name": "Personal notes - read only",
+      "pageId": "12345678-1234-1234-1234-123456789abc",
+      "permissions": ["page:read", "database:read", "database:query", "block:read"]
+    },
+    {
+      // Example 2: Read + block append only (no page property updates, no delete)
+      // Use case: Reference documents that AI can add notes to but not modify
+      "name": "Reference docs - read and append",
+      "pageId": "11111111-1111-1111-1111-111111111111",
+      "permissions": ["page:read", "database:read", "database:query", "block:read", "block:append"]
+    },
+    {
+      // Example 3: Database with conditional access
+      // Only allows access when Assignee property matches the specified user
+      "name": "Work tasks - conditional",
+      "databaseId": "abcdef12-3456-7890-abcd-ef1234567890",
+      "permissions": ["page:read", "database:read", "database:query", "block:read", "page:update", "block:append", "page:create", "database:create"],
+      "condition": {
+        "property": "Assignee",
+        "type": "people",
+        "equals": "user-id-from-notion"  // Replace with actual user ID
+      }
+    },
+    {
+      // Example 4: Database query and create only (no updates to existing pages)
+      // Use case: Task database where AI can create new tasks but not modify existing ones
+      "name": "Task DB - query and create only",
+      "databaseId": "22222222-2222-2222-2222-222222222222",
+      "permissions": ["database:read", "database:query", "database:create"]
+    },
+    {
+      // Example 5: Database with status-based condition
+      // Only allows access when Status is "In Progress"
+      "name": "Project tracker - status conditional",
+      "databaseId": "fedcba98-7654-3210-fedc-ba9876543210",
+      "permissions": ["page:read", "database:read", "database:query", "block:read", "page:update", "block:append"],
+      "condition": {
+        "property": "Status",
+        "type": "status",
+        "equals": "In Progress"
+      }
+    },
+    {
+      // Example 6: Full access to a workspace page
+      "name": "AI Workspace - full access",
+      "pageId": "workspace-page-id-here",
+      "permissions": ["page:read", "page:update", "page:create", "database:read", "database:query", "database:create", "block:read", "block:append", "block:delete"]
+    },
+    {
+      // Example 7: Database with checkbox condition
+      // Only allows access when "AI Editable" checkbox is true
+      "name": "Shared DB - checkbox conditional",
+      "databaseId": "shared-db-id-here",
+      "permissions": ["page:read", "database:read", "database:query", "block:read", "page:update", "block:append"],
+      "condition": {
+        "property": "AI Editable",
+        "type": "checkbox",
+        "equals": true
+      }
+    }
+  ],
+  // Default behavior when no rule matches
+  // "deny" - Block all access (recommended for safety)
+  // "read" - Allow read-only access
+  "defaultPermission": "deny"
+}

package/dist/commands/block.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createBlockCommand(): Command;

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createConfigCommand(): Command;

package/dist/commands/db.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createDbCommand(): Command;

package/dist/commands/page.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createPageCommand(): Command;

package/dist/commands/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function outputJson(data: unknown): void;
+export declare function handleError(error: unknown): never;

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import { type Config } from "./types.ts";
+export declare function getConfigPath(): string;
+export declare function loadConfig(): Config;
+export declare function validateConfig(configPath?: string): {
+    valid: boolean;
+    errors?: string[];
+};
+export declare function initConfig(): string;
+export declare function getNotionToken(): string;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/index.js

@@ -0,0 +1,679 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/index.ts
+import { Command as Command5 } from "commander";
+
+// src/commands/page.ts
+import { Command } from "commander";
+
+// src/notion-client.ts
+import { Client } from "@notionhq/client";
+
+// src/config.ts
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { parse as parseJsonc } from "jsonc-parser";
+
+// src/types.ts
+import { z } from "zod";
+var GranularPermissionValues = [
+  "page:read",
+  "page:update",
+  "page:create",
+  "database:read",
+  "database:query",
+  "database:create",
+  "block:read",
+  "block:append",
+  "block:delete"
+];
+var PermissionSchema = z.enum(GranularPermissionValues);
+var ConditionSchema = z.object({
+  property: z.string(),
+  type: z.enum(["people", "select", "multi_select", "status", "checkbox"]),
+  equals: z.union([z.string(), z.boolean()])
+});
+var RuleSchema = z.object({
+  name: z.string(),
+  pageId: z.string().uuid().optional(),
+  databaseId: z.string().uuid().optional(),
+  permissions: z.array(PermissionSchema),
+  condition: ConditionSchema.optional()
+}).refine((data) => data.pageId || data.databaseId, {
+  message: "Either pageId or databaseId must be specified"
+});
+var ConfigSchema = z.object({
+  rules: z.array(RuleSchema),
+  defaultPermission: z.enum(["deny", "read"]).default("deny")
+});
+
+// src/config.ts
+var CONFIG_DIR = join(homedir(), ".config", "safe-notion");
+var CONFIG_PATH = join(CONFIG_DIR, "config.jsonc");
+function getConfigPath() {
+  return CONFIG_PATH;
+}
+function loadConfig() {
+  if (!existsSync(CONFIG_PATH)) {
+    throw new Error(`Config file not found: ${CONFIG_PATH}
+Run 'notion-safe config init' to create a template.`);
+  }
+  const content = readFileSync(CONFIG_PATH, "utf-8");
+  const parsed = parseJsonc(content);
+  const result = ConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    const errors = result.error.issues.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join(`
+`);
+    throw new Error(`Invalid config file:
+${errors}`);
+  }
+  return result.data;
+}
+function validateConfig(configPath) {
+  const path = configPath ?? CONFIG_PATH;
+  if (!existsSync(path)) {
+    return { valid: false, errors: [`Config file not found: ${path}`] };
+  }
+  try {
+    const content = readFileSync(path, "utf-8");
+    const parsed = parseJsonc(content);
+    const result = ConfigSchema.safeParse(parsed);
+    if (!result.success) {
+      return {
+        valid: false,
+        errors: result.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`)
+      };
+    }
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [error instanceof Error ? error.message : "Unknown error"]
+    };
+  }
+}
+function initConfig() {
+  if (existsSync(CONFIG_PATH)) {
+    throw new Error(`Config file already exists: ${CONFIG_PATH}`);
+  }
+  const template = `{
+  // Safe Notion - Configuration
+  // Rules are evaluated in order; first matching rule applies
+  //
+  // Permission types (granular format):
+  //   page:read, page:update, page:create
+  //   database:read, database:query, database:create
+  //   block:read, block:append, block:delete
+  "rules": [
+    {
+      // Rule name (for logging)
+      "name": "Example - Read only page",
+      // Page ID (applies to this page and all children)
+      "pageId": "00000000-0000-0000-0000-000000000000",
+      "permissions": ["page:read", "database:read", "database:query", "block:read"]
+    },
+    {
+      "name": "Example - Read + block append only",
+      // Allows reading and adding blocks, but NOT updating page properties or deleting
+      "pageId": "11111111-1111-1111-1111-111111111111",
+      "permissions": ["page:read", "database:read", "database:query", "block:read", "block:append"]
+    },
+    {
+      "name": "Example - Database with conditional write",
+      // Database ID
+      "databaseId": "22222222-2222-2222-2222-222222222222",
+      "permissions": ["page:read", "database:read", "database:query", "block:read", "page:update", "block:append"],
+      // Optional: Only allow if this condition is met
+      "condition": {
+        "property": "Assignee",  // Property name
+        "type": "people",        // Property type: people, select, multi_select, status, checkbox
+        "equals": "user-id"      // Value to match (user ID for people, string for others)
+      }
+    },
+    {
+      "name": "Example - Database query and create only",
+      // Allows querying and creating pages in DB, but NOT updating existing pages
+      "databaseId": "33333333-3333-3333-3333-333333333333",
+      "permissions": ["database:read", "database:query", "database:create"]
+    },
+    {
+      "name": "Example - Full access page",
+      "pageId": "44444444-4444-4444-4444-444444444444",
+      "permissions": ["page:read", "page:update", "page:create", "database:read", "database:query", "database:create", "block:read", "block:append", "block:delete"]
+    }
+  ],
+  // Default behavior when no rule matches: "deny" or "read"
+  "defaultPermission": "deny"
+}
+`;
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, template, "utf-8");
+  return CONFIG_PATH;
+}
+function getNotionToken() {
+  const token = process.env.NOTION_TOKEN;
+  if (!token) {
+    throw new Error(`NOTION_TOKEN environment variable is not set.
+` + "Get your API token from https://www.notion.so/my-integrations");
+  }
+  return token;
+}
+
+// src/permissions.ts
+var parentCache = new Map;
+var CACHE_TTL_MS = 10 * 60 * 1000;
+function normalizeId(id) {
+  return id.replace(/-/g, "").toLowerCase();
+}
+function idsMatch(id1, id2) {
+  return normalizeId(id1) === normalizeId(id2);
+}
+async function getParentId(client, resourceId) {
+  const normalizedId = normalizeId(resourceId);
+  const now = Date.now();
+  const cached = parentCache.get(normalizedId);
+  if (cached && cached.expiresAt > now) {
+    return cached.value;
+  }
+  try {
+    const page = await client.pages.retrieve({ page_id: resourceId });
+    if ("parent" in page) {
+      let parentId = null;
+      if (page.parent.type === "page_id") {
+        parentId = page.parent.page_id;
+      } else if (page.parent.type === "database_id") {
+        parentId = page.parent.database_id;
+      } else if (page.parent.type === "data_source_id" && "database_id" in page.parent) {
+        parentId = page.parent.database_id;
+      }
+      parentCache.set(normalizedId, { value: parentId, expiresAt: now + CACHE_TTL_MS });
+      return parentId;
+    }
+  } catch {
+    try {
+      const block = await client.blocks.retrieve({ block_id: resourceId });
+      if ("parent" in block) {
+        let parentId = null;
+        if (block.parent.type === "page_id") {
+          parentId = block.parent.page_id;
+        } else if (block.parent.type === "database_id") {
+          parentId = block.parent.database_id;
+        } else if (block.parent.type === "block_id") {
+          parentId = block.parent.block_id;
+        }
+        parentCache.set(normalizedId, { value: parentId, expiresAt: now + CACHE_TTL_MS });
+        return parentId;
+      }
+    } catch {
+      try {
+        const db = await client.databases.retrieve({ database_id: resourceId });
+        if ("parent" in db) {
+          let parentId = null;
+          if (db.parent.type === "page_id") {
+            parentId = db.parent.page_id;
+          }
+          parentCache.set(normalizedId, { value: parentId, expiresAt: now + CACHE_TTL_MS });
+          return parentId;
+        }
+      } catch {}
+    }
+  }
+  parentCache.set(normalizedId, { value: null, expiresAt: now + CACHE_TTL_MS });
+  return null;
+}
+async function isDescendantOf(client, resourceId, ancestorId, maxDepth = 10) {
+  if (idsMatch(resourceId, ancestorId)) {
+    return true;
+  }
+  let currentId = resourceId;
+  let depth = 0;
+  while (currentId && depth < maxDepth) {
+    const parentId = await getParentId(client, currentId);
+    if (!parentId) {
+      return false;
+    }
+    if (idsMatch(parentId, ancestorId)) {
+      return true;
+    }
+    currentId = parentId;
+    depth++;
+  }
+  return false;
+}
+async function checkCondition(client, pageId, condition) {
+  try {
+    const page = await client.pages.retrieve({ page_id: pageId });
+    if (!("properties" in page)) {
+      return false;
+    }
+    const property = page.properties[condition.property];
+    if (!property) {
+      return false;
+    }
+    switch (condition.type) {
+      case "people": {
+        if (property.type !== "people")
+          return false;
+        return property.people.some((p) => p.id === condition.equals);
+      }
+      case "select": {
+        if (property.type !== "select")
+          return false;
+        return property.select?.name === condition.equals;
+      }
+      case "multi_select": {
+        if (property.type !== "multi_select")
+          return false;
+        return property.multi_select.some((s) => s.name === condition.equals);
+      }
+      case "status": {
+        if (property.type !== "status")
+          return false;
+        return property.status?.name === condition.equals;
+      }
+      case "checkbox": {
+        if (property.type !== "checkbox")
+          return false;
+        return property.checkbox === condition.equals;
+      }
+      default:
+        return false;
+    }
+  } catch {
+    return false;
+  }
+}
+async function checkPermission(client, config, resourceId, operation, pageIdForCondition) {
+  for (const rule of config.rules) {
+    let matches = false;
+    if (rule.pageId) {
+      matches = await isDescendantOf(client, resourceId, rule.pageId);
+    } else if (rule.databaseId) {
+      if (idsMatch(resourceId, rule.databaseId)) {
+        matches = true;
+      } else {
+        const parentId = await getParentId(client, resourceId);
+        if (parentId && idsMatch(parentId, rule.databaseId)) {
+          matches = true;
+        }
+      }
+    }
+    if (matches) {
+      const rulePermissions = new Set(rule.permissions);
+      const hasPermission = rulePermissions.has(operation);
+      if (!hasPermission) {
+        return {
+          allowed: false,
+          rule,
+          reason: `Operation '${operation}' not allowed by rule '${rule.name}'`
+        };
+      }
+      const writeOperations = [
+        "page:update",
+        "block:append",
+        "page:create",
+        "database:create"
+      ];
+      if (writeOperations.includes(operation) && rule.condition) {
+        const targetPageId = pageIdForCondition ?? resourceId;
+        const conditionMet = await checkCondition(client, targetPageId, rule.condition);
+        if (!conditionMet) {
+          return {
+            allowed: false,
+            rule,
+            reason: `Condition not met: ${rule.condition.property} must equal '${rule.condition.equals}'`
+          };
+        }
+      }
+      return {
+        allowed: true,
+        rule,
+        reason: `Allowed by rule '${rule.name}'`
+      };
+    }
+  }
+  const readOperations = [
+    "page:read",
+    "database:read",
+    "database:query",
+    "block:read"
+  ];
+  if (config.defaultPermission === "read" && readOperations.includes(operation)) {
+    return {
+      allowed: true,
+      reason: "Allowed by default read permission"
+    };
+  }
+  return {
+    allowed: false,
+    reason: "No matching rule and default permission is deny"
+  };
+}
+function clearCache() {
+  parentCache.clear();
+}
+
+// src/notion-client.ts
+class NotionSafeClient {
+  client;
+  config;
+  constructor() {
+    const token = getNotionToken();
+    this.client = new Client({ auth: token });
+    this.config = loadConfig();
+  }
+  async ensurePermission(resourceId, operation, pageIdForCondition) {
+    const result = await checkPermission(this.client, this.config, resourceId, operation, pageIdForCondition);
+    if (!result.allowed) {
+      const error = {
+        error: result.reason,
+        code: "PERMISSION_DENIED"
+      };
+      throw error;
+    }
+  }
+  async getPage(pageId) {
+    await this.ensurePermission(pageId, "page:read");
+    return this.client.pages.retrieve({ page_id: pageId });
+  }
+  async createPage(params) {
+    let parentId;
+    if (params.parent && "page_id" in params.parent) {
+      parentId = params.parent.page_id;
+    } else if (params.parent && "database_id" in params.parent) {
+      parentId = params.parent.database_id;
+    } else {
+      throw { error: "Invalid parent type", code: "INVALID_PARENT" };
+    }
+    await this.ensurePermission(parentId, "page:create");
+    return this.client.pages.create(params);
+  }
+  async updatePage(pageId, properties) {
+    await this.ensurePermission(pageId, "page:update", pageId);
+    return this.client.pages.update({ page_id: pageId, properties });
+  }
+  async getDatabase(databaseId) {
+    await this.ensurePermission(databaseId, "database:read");
+    return this.client.databases.retrieve({ database_id: databaseId });
+  }
+  async queryDatabase(databaseId, params) {
+    await this.ensurePermission(databaseId, "database:query");
+    return this.client.databases.query({
+      database_id: databaseId,
+      ...params
+    });
+  }
+  async createDatabasePage(databaseId, properties) {
+    await this.ensurePermission(databaseId, "database:create");
+    return this.client.pages.create({
+      parent: { database_id: databaseId },
+      properties
+    });
+  }
+  async getBlock(blockId) {
+    await this.ensurePermission(blockId, "block:read");
+    return this.client.blocks.retrieve({ block_id: blockId });
+  }
+  async getBlockChildren(blockId, startCursor, pageSize) {
+    await this.ensurePermission(blockId, "block:read");
+    return this.client.blocks.children.list({
+      block_id: blockId,
+      start_cursor: startCursor,
+      page_size: pageSize
+    });
+  }
+  async appendBlockChildren(blockId, children) {
+    await this.ensurePermission(blockId, "block:append");
+    return this.client.blocks.children.append({
+      block_id: blockId,
+      children
+    });
+  }
+  async deleteBlock(blockId) {
+    await this.ensurePermission(blockId, "block:delete");
+    return this.client.blocks.delete({ block_id: blockId });
+  }
+  clearCache() {
+    clearCache();
+  }
+}
+var clientInstance = null;
+function getClient() {
+  if (!clientInstance) {
+    clientInstance = new NotionSafeClient;
+  }
+  return clientInstance;
+}
+
+// src/commands/utils.ts
+function outputJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function handleError(error) {
+  if (isErrorResponse(error)) {
+    outputJson(error);
+    process.exit(1);
+  }
+  if (error instanceof Error) {
+    const response2 = {
+      error: error.message,
+      code: "UNKNOWN_ERROR"
+    };
+    outputJson(response2);
+    process.exit(1);
+  }
+  if (isNotionError(error)) {
+    const response2 = {
+      error: error.message,
+      code: error.code
+    };
+    outputJson(response2);
+    process.exit(1);
+  }
+  const response = {
+    error: String(error),
+    code: "UNKNOWN_ERROR"
+  };
+  outputJson(response);
+  process.exit(1);
+}
+function isErrorResponse(error) {
+  return typeof error === "object" && error !== null && "error" in error && "code" in error;
+}
+function isNotionError(error) {
+  return typeof error === "object" && error !== null && "message" in error && "code" in error;
+}
+
+// src/commands/page.ts
+function createPageCommand() {
+  const page = new Command("page").description("Page operations");
+  page.command("get").description("Get a page by ID").argument("<page-id>", "Page ID").action(async (pageId) => {
+    try {
+      const client = getClient();
+      const result = await client.getPage(pageId);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  page.command("create").description("Create a new page").requiredOption("--parent <id>", "Parent page ID").requiredOption("--title <title>", "Page title").option("--icon <emoji>", "Page icon emoji").option("--content <json>", "Page content as JSON array of blocks").action(async (options) => {
+    try {
+      const client = getClient();
+      const properties = {
+        title: {
+          title: [{ text: { content: options.title } }]
+        }
+      };
+      const params = {
+        parent: { page_id: options.parent },
+        properties
+      };
+      if (options.icon) {
+        params.icon = { emoji: options.icon };
+      }
+      if (options.content) {
+        params.children = JSON.parse(options.content);
+      }
+      const result = await client.createPage(params);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  page.command("update").description("Update a page").argument("<page-id>", "Page ID").requiredOption("--properties <json>", "Properties to update as JSON").action(async (pageId, options) => {
+    try {
+      const client = getClient();
+      const properties = JSON.parse(options.properties);
+      const result = await client.updatePage(pageId, properties);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  return page;
+}
+
+// src/commands/db.ts
+import { Command as Command2 } from "commander";
+function createDbCommand() {
+  const db = new Command2("db").description("Database operations");
+  db.command("get").description("Get a database by ID").argument("<database-id>", "Database ID").action(async (databaseId) => {
+    try {
+      const client = getClient();
+      const result = await client.getDatabase(databaseId);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  db.command("query").description("Query a database").argument("<database-id>", "Database ID").option("--filter <json>", "Filter as JSON").option("--sorts <json>", "Sorts as JSON array").option("--start-cursor <cursor>", "Pagination cursor").option("--page-size <size>", "Number of results per page", "100").action(async (databaseId, options) => {
+    try {
+      const client = getClient();
+      const params = {};
+      if (options.filter) {
+        params.filter = JSON.parse(options.filter);
+      }
+      if (options.sorts) {
+        params.sorts = JSON.parse(options.sorts);
+      }
+      if (options.startCursor) {
+        params.start_cursor = options.startCursor;
+      }
+      if (options.pageSize) {
+        params.page_size = parseInt(options.pageSize, 10);
+      }
+      const result = await client.queryDatabase(databaseId, params);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  db.command("create-page").description("Create a new page in a database").argument("<database-id>", "Database ID").requiredOption("--properties <json>", "Page properties as JSON").action(async (databaseId, options) => {
+    try {
+      const client = getClient();
+      const properties = JSON.parse(options.properties);
+      const result = await client.createDatabasePage(databaseId, properties);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  return db;
+}
+
+// src/commands/block.ts
+import { Command as Command3 } from "commander";
+function createBlockCommand() {
+  const block = new Command3("block").description("Block operations");
+  block.command("get").description("Get a block by ID").argument("<block-id>", "Block ID").action(async (blockId) => {
+    try {
+      const client = getClient();
+      const result = await client.getBlock(blockId);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  block.command("children").description("Get children of a block").argument("<block-id>", "Block ID (can also be a page ID)").option("--start-cursor <cursor>", "Pagination cursor").option("--page-size <size>", "Number of results per page").action(async (blockId, options) => {
+    try {
+      const client = getClient();
+      const result = await client.getBlockChildren(blockId, options.startCursor, options.pageSize ? parseInt(options.pageSize, 10) : undefined);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  block.command("append").description("Append children to a block").argument("<block-id>", "Block ID (can also be a page ID)").requiredOption("--children <json>", "Children blocks as JSON array").action(async (blockId, options) => {
+    try {
+      const client = getClient();
+      const children = JSON.parse(options.children);
+      const result = await client.appendBlockChildren(blockId, children);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  block.command("delete").description("Delete a block").argument("<block-id>", "Block ID").action(async (blockId) => {
+    try {
+      const client = getClient();
+      const result = await client.deleteBlock(blockId);
+      outputJson(result);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  return block;
+}
+
+// src/commands/config.ts
+import { Command as Command4 } from "commander";
+function createConfigCommand() {
+  const config = new Command4("config").description("Configuration management");
+  config.command("validate").description("Validate the configuration file").option("--path <path>", "Path to config file").action((options) => {
+    try {
+      const result = validateConfig(options.path);
+      if (result.valid) {
+        outputJson({
+          valid: true,
+          path: options.path ?? getConfigPath()
+        });
+      } else {
+        outputJson({
+          valid: false,
+          errors: result.errors,
+          path: options.path ?? getConfigPath()
+        });
+        process.exit(1);
+      }
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  config.command("init").description("Create a template configuration file").action(() => {
+    try {
+      const path = initConfig();
+      outputJson({
+        success: true,
+        path,
+        message: "Configuration template created. Edit it to add your rules."
+      });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  config.command("path").description("Show the configuration file path").action(() => {
+    outputJson({ path: getConfigPath() });
+  });
+  return config;
+}
+
+// src/index.ts
+var program = new Command5;
+program.name("notion-safe").description("A safe Notion API wrapper CLI for AI agents").version("0.1.0");
+program.addCommand(createPageCommand());
+program.addCommand(createDbCommand());
+program.addCommand(createBlockCommand());
+program.addCommand(createConfigCommand());
+program.parse();

package/dist/notion-client.d.ts

@@ -0,0 +1,29 @@
+import { Client } from "@notionhq/client";
+type CreatePageParams = Parameters<Client["pages"]["create"]>[0];
+type UpdatePageParams = Parameters<Client["pages"]["update"]>[0];
+type AppendBlockChildrenParams = Parameters<Client["blocks"]["children"]["append"]>[0];
+interface QueryParams {
+    filter?: unknown;
+    sorts?: unknown[];
+    start_cursor?: string;
+    page_size?: number;
+}
+export declare class NotionSafeClient {
+    private client;
+    private config;
+    constructor();
+    private ensurePermission;
+    getPage(pageId: string): Promise<unknown>;
+    createPage(params: CreatePageParams): Promise<unknown>;
+    updatePage(pageId: string, properties: UpdatePageParams["properties"]): Promise<unknown>;
+    getDatabase(databaseId: string): Promise<unknown>;
+    queryDatabase(databaseId: string, params?: QueryParams): Promise<unknown>;
+    createDatabasePage(databaseId: string, properties: CreatePageParams["properties"]): Promise<unknown>;
+    getBlock(blockId: string): Promise<unknown>;
+    getBlockChildren(blockId: string, startCursor?: string, pageSize?: number): Promise<unknown>;
+    appendBlockChildren(blockId: string, children: AppendBlockChildrenParams["children"]): Promise<unknown>;
+    deleteBlock(blockId: string): Promise<unknown>;
+    clearCache(): void;
+}
+export declare function getClient(): NotionSafeClient;
+export {};

package/dist/permissions.d.ts

@@ -0,0 +1,4 @@
+import { Client } from "@notionhq/client";
+import type { Config, OperationType, PermissionCheckResult } from "./types.ts";
+export declare function checkPermission(client: Client, config: Config, resourceId: string, operation: OperationType, pageIdForCondition?: string): Promise<PermissionCheckResult>;
+export declare function clearCache(): void;

package/dist/types.d.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+export declare const GranularPermissionValues: readonly ["page:read", "page:update", "page:create", "database:read", "database:query", "database:create", "block:read", "block:append", "block:delete"];
+export type GranularPermission = (typeof GranularPermissionValues)[number];
+export declare const PermissionSchema: z.ZodEnum<{
+    "page:read": "page:read";
+    "page:update": "page:update";
+    "page:create": "page:create";
+    "database:read": "database:read";
+    "database:query": "database:query";
+    "database:create": "database:create";
+    "block:read": "block:read";
+    "block:append": "block:append";
+    "block:delete": "block:delete";
+}>;
+export type Permission = z.infer<typeof PermissionSchema>;
+export declare const ConditionSchema: z.ZodObject<{
+    property: z.ZodString;
+    type: z.ZodEnum<{
+        people: "people";
+        select: "select";
+        multi_select: "multi_select";
+        status: "status";
+        checkbox: "checkbox";
+    }>;
+    equals: z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>;
+}, z.core.$strip>;
+export type Condition = z.infer<typeof ConditionSchema>;
+export declare const RuleSchema: z.ZodObject<{
+    name: z.ZodString;
+    pageId: z.ZodOptional<z.ZodString>;
+    databaseId: z.ZodOptional<z.ZodString>;
+    permissions: z.ZodArray<z.ZodEnum<{
+        "page:read": "page:read";
+        "page:update": "page:update";
+        "page:create": "page:create";
+        "database:read": "database:read";
+        "database:query": "database:query";
+        "database:create": "database:create";
+        "block:read": "block:read";
+        "block:append": "block:append";
+        "block:delete": "block:delete";
+    }>>;
+    condition: z.ZodOptional<z.ZodObject<{
+        property: z.ZodString;
+        type: z.ZodEnum<{
+            people: "people";
+            select: "select";
+            multi_select: "multi_select";
+            status: "status";
+            checkbox: "checkbox";
+        }>;
+        equals: z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Rule = z.infer<typeof RuleSchema>;
+export declare const ConfigSchema: z.ZodObject<{
+    rules: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        pageId: z.ZodOptional<z.ZodString>;
+        databaseId: z.ZodOptional<z.ZodString>;
+        permissions: z.ZodArray<z.ZodEnum<{
+            "page:read": "page:read";
+            "page:update": "page:update";
+            "page:create": "page:create";
+            "database:read": "database:read";
+            "database:query": "database:query";
+            "database:create": "database:create";
+            "block:read": "block:read";
+            "block:append": "block:append";
+            "block:delete": "block:delete";
+        }>>;
+        condition: z.ZodOptional<z.ZodObject<{
+            property: z.ZodString;
+            type: z.ZodEnum<{
+                people: "people";
+                select: "select";
+                multi_select: "multi_select";
+                status: "status";
+                checkbox: "checkbox";
+            }>;
+            equals: z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    defaultPermission: z.ZodDefault<z.ZodEnum<{
+        deny: "deny";
+        read: "read";
+    }>>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof ConfigSchema>;
+export interface PermissionCheckResult {
+    allowed: boolean;
+    rule?: Rule;
+    reason: string;
+}
+export interface ErrorResponse {
+    error: string;
+    code: string;
+}
+export type OperationType = GranularPermission;
+export type ResourceType = "page" | "database" | "block";
+export interface ResourceIdentifier {
+    type: ResourceType;
+    id: string;
+    parentId?: string;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "safe-notion",
+  "version": "0.1.0",
+  "description": "A safe Notion API wrapper CLI for AI agents with granular permission control",
+  "license": "MIT",
+  "author": "shoppingjaws",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shoppingjaws/safe-notion.git"
+  },
+  "homepage": "https://github.com/shoppingjaws/safe-notion#readme",
+  "bugs": {
+    "url": "https://github.com/shoppingjaws/safe-notion/issues"
+  },
+  "keywords": [
+    "notion",
+    "notion-api",
+    "cli",
+    "ai",
+    "agent",
+    "permission",
+    "security",
+    "mcp"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "notion-safe": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "config.sample.jsonc"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --packages external && bun run build:types",
+    "build:types": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "dependencies": {
+    "@notionhq/client": "^5.8.0",
+    "commander": "^14.0.2",
+    "jsonc-parser": "^3.3.1",
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}