CodeLock

Offline-first protection for source files that matter.

CodeLock lets a developer mark files and folders as protected. When an IDE or CLI operation tries to change a protected resource, the Python engine evaluates the project policy and allows, warns, password-gates, or blocks the change.

This is a production-quality MVP. It is honest about what it can and cannot enforce.

---

What CodeLock is

A local protection engine plus a VS Code-compatible extension (works in Cursor where the host exposes the same extension APIs).

It is not a cloud product. There is no account, license server, telemetry, or remote API.

Why it exists

AI coding agents are useful and also fast enough to edit the wrong file. Payroll calculators, auth code, and database migrations should not change because an agent got enthusiastic.

CodeLock makes that intent explicit and enforceable inside the IDE integration, with a password and an audit trail.

Current capabilities

• Protect a file or folder with its own password; unlock that item only
• Three primary modes in the UI: Password, Block, Warn
• Per-resource permissions: View, Edit, Rename, Delete (each enforced in the engine)
• Encrypted at rest for password-protected files when View is protected (AES-256-GCM vault under .codelock/vault/)
• Unlock sessions default to until manually locked (configurable: 5m–4h, until IDE closes, once)
• Project policy file (YAML, no secrets) — optional Advanced Rules
• Argon2id password hashing (per lock; never stored in policy)
• Local audit log with actor/action/result
• Python CLI: protect, unlock, lock, read, check, status, audit
• Central authorize() decision engine in Python core
• Offline operation

Further reading: SECURITY.md, PRIVACY.md, THREAT_MODEL.md, POLICY_GUIDE.md, docs/architecture/overview.md.

Important limitations

CodeLock uses three layers with different strength:

Layer	What it protects	What it cannot do
IDE integration	Editor open/save/rename/delete, AI edit paths exposed by VS Code/Cursor	Arbitrary Get-Content, git, other editors, malware, admin access
CLI (codelock read)	Controlled read/decrypt for protected resources	Intercept raw PowerShell/CMD file access
Encrypted at rest	Plaintext not left on disk for protected files (when View is protected)	Stop a kernel-level attacker or forced disk imaging

A VS Code extension cannot stop every process on the machine. When encrypted-at-rest is active, Get-Content on the original path sees only a CodeLock stub — not plaintext. Direct vault blob access still requires the password-derived key.

Read docs/limitations.md and docs/security-model.md before treating CodeLock as a security boundary.

---

Sample data (dummy examples)

The following is illustrative dummy data — not real secrets or production configuration.

Example protected resources dashboard

CODELOCK — Protected Resources

🔐 src/payment/service.ts
   Password · View · Edit · Rename · Delete

🔐 src/auth/
   Password · View · Edit

🚫 .env
   Blocked

⚠️ README.md
   Warn before edit

Example project layout

my-app/
├── .codelock/
│   ├── policy.yaml
│   └── vault/
│       ├── content-index.json
│       └── blobs/
│           └── a1b2c3d4....bin
├── src/
│   ├── payment/
│   │   └── service.ts      ← stub on disk when encrypted
│   └── auth/
│       └── login.ts
└── .env                    ← blocked (no password)

Example policy.yaml (no passwords stored)

version: 1
rules:
  - path: src/payment/service.ts
    mode: password
    lock_id: lock_pay_01
    actions: [read, edit, rename, delete]
  - path: src/auth/**
    mode: password
    lock_id: lock_auth_02
    actions: [read, edit]
  - path: .env
    mode: block
  - path: README.md
    mode: warn
    actions: [edit]

Example CLI output

> codelock status
Project: C:\projects\my-app
Policy:  C:\projects\my-app\.codelock\policy.yaml
Rules:   4  (password=2 warn=1 block=1 allow=0)
Unlocked: no

> codelock check
CodeLock Security Check
========================
✓ passwords_not_in_policy: Policy file contains no password material.
✓ encrypted_at_rest: 1 resource(s) encrypted in vault.
✓ ide_enforcement: VS Code/Cursor extension enforces save/edit/rename/delete in the IDE.
✓ cli_read_enforcement: Use `codelock read` for CLI access to encrypted resources.
⚠ powershell_limitation: Direct PowerShell Get-Content cannot be intercepted by a VS Code extension.
Encrypted resources: 1
Protection rules: 4

Example audit history (dummy)

Time	Actor	Action	Resource	Result	Reason
09:20	AI	READ	src/payment/service.ts	BLOCKED	Password required
09:22	Developer	EDIT	src/payment/service.ts	ALLOWED	Authenticated
09:23	External	MODIFY	src/payment/service.ts	DETECTED	Integrity check

Example stub file on disk (encrypted-at-rest)

---CODELOCK-PROTECTED---
vault_id=dummy_vault_id_001

Plaintext is not in this file when encryption is active — only the stub above.

---

Architecture

VS Code / Cursor
       │
       ▼
TypeScript Extension
       │
       ▼
Local IPC (JSON-RPC over stdio)
       │
       ▼
Python Protection Engine
       │
 ┌─────┼─────┐
 ▼     ▼     ▼
Policy Security Audit
       │
       ▼
Local Storage

There is one source of truth: core/codelock. The extension and CLI do not re-implement policy.

Details: docs/architecture.md, docs/ipc.md.

---

Installation

Requirements

• Python 3.11+ (developed on 3.14)
• Node.js 18+
• VS Code 1.85+ or Cursor with extension host support

Extension

Install from the Visual Studio Marketplace or Open VSX.

code --install-extension codelock.codelock

Python engine (development)

cd core
pip install -e ".[dev]"

Tests

python -m pytest

See docs/development/testing.md.

---

License

MIT