Notion Policy & Guardrails

Overview

Automated policy enforcement and guardrails for Notion integrations.

Prerequisites

• ESLint configured in project
• Pre-commit hooks infrastructure
• CI/CD pipeline with policy checks
• TypeScript for type enforcement

ESLint Rules

Custom Notion Plugin

// eslint-plugin-notion/rules/no-hardcoded-keys.js
module.exports = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow hardcoded Notion API keys',
    },
    fixable: 'code',
  },
  create(context) {
    return {
      Literal(node) {
        if (typeof node.value === 'string') {
          if (node.value.match(/^sk_(live|test)_[a-zA-Z0-9]{24,}/)) {
            context.report({
              node,
              message: 'Hardcoded Notion API key detected',
            });
          }
        }
      },
    };
  },
};

ESLint Configuration

// .eslintrc.js
module.exports = {
  plugins: ['notion'],
  rules: {
    'notion/no-hardcoded-keys': 'error',
    'notion/require-error-handling': 'warn',
    'notion/use-typed-client': 'warn',
  },
};

Pre-Commit Hooks

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: notion-secrets-check
        name: Check for Notion secrets
        entry: bash -c 'git diff --cached --name-only | xargs grep -l "sk_live_" && exit 1 || exit 0'
        language: system
        pass_filenames: false

      - id: notion-config-validate
        name: Validate Notion configuration
        entry: node scripts/validate-notion-config.js
        language: node
        files: '\.notion\.json$'

TypeScript Strict Patterns

// Enforce typed configuration
interface NotionStrictConfig {
  apiKey: string;  // Required
  environment: 'development' | 'staging' | 'production';  // Enum
  timeout: number;  // Required number, not optional
  retries: number;
}

// Disallow any in Notion code
// @ts-expect-error - Using any is forbidden
const client = new Client({ apiKey: any });

// Prefer this
const client = new NotionClient(config satisfies NotionStrictConfig);

Architecture Decision Records

ADR Template

# ADR-001: Notion Client Initialization

## Status
Accepted

## Context
We need to decide how to initialize the Notion client across our application.

## Decision
We will use the singleton pattern with lazy initialization.

## Consequences
- Pro: Single client instance, connection reuse
- Pro: Easy to mock in tests
- Con: Global state requires careful lifecycle management

## Enforcement
- ESLint rule: notion/use-singleton-client
- CI check: grep for "new NotionClient(" outside allowed files

Policy-as-Code (OPA)

# notion-policy.rego
package notion

# Deny production API keys in non-production environments
deny[msg] {
  input.environment != "production"
  startswith(input.apiKey, "sk_live_")
  msg := "Production API keys not allowed in non-production environment"
}

# Require minimum timeout
deny[msg] {
  input.timeout < 10000
  msg := sprintf("Timeout too low: %d < 10000ms minimum", [input.timeout])
}

# Require retry configuration
deny[msg] {
  not input.retries
  msg := "Retry configuration is required"
}

CI Policy Checks

# .github/workflows/notion-policy.yml
name: Notion Policy Check

on: [push, pull_request]

jobs:
  policy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check for hardcoded secrets
        run: |
          if grep -rE "sk_(live|test)_[a-zA-Z0-9]{24,}" --include="*.ts" --include="*.js" .; then
            echo "ERROR: Hardcoded Notion keys found"
            exit 1
          fi

      - name: Validate configuration schema
        run: |
          npx ajv validate -s notion-config.schema.json -d config/notion/*.json

      - name: Run ESLint Notion rules
        run: npx eslint --plugin notion --rule 'notion/no-hardcoded-keys: error' src/

Runtime Guardrails

// Prevent dangerous operations in production
const BLOCKED_IN_PROD = ['deleteAll', 'resetData', 'migrateDown'];

function guardNotionOperation(operation: string): void {
  const isProd = process.env.NODE_ENV === 'production';

  if (isProd && BLOCKED_IN_PROD.includes(operation)) {
    throw new Error(`Operation '${operation}' blocked in production`);
  }
}

// Rate limit protection
function guardRateLimits(requestsInWindow: number): void {
  const limit = parseInt(process.env.NOTION_RATE_LIMIT || '100');

  if (requestsInWindow > limit * 0.9) {
    console.warn('Approaching Notion rate limit');
  }

  if (requestsInWindow >= limit) {
    throw new Error('Notion rate limit exceeded - request blocked');
  }
}

Instructions

Step 1: Create ESLint Rules

Implement custom lint rules for Notion patterns.

Step 2: Configure Pre-Commit Hooks

Set up hooks to catch issues before commit.

Step 3: Add CI Policy Checks

Implement policy-as-code in CI pipeline.

Step 4: Enable Runtime Guardrails

Add production safeguards for dangerous operations.

Output

• ESLint plugin with Notion rules
• Pre-commit hooks blocking secrets
• CI policy checks passing
• Runtime guardrails active

Error Handling

Examples

Quick ESLint Check

npx eslint --plugin notion --rule 'notion/no-hardcoded-keys: error' src/

Resources

• ESLint Plugin Development
• Pre-commit Framework
• Open Policy Agent

Next Steps

For architecture blueprints, see notion-architecture-variants.