MDflow for VS Code

Browse and edit your MDflow workspaces, folders, and markdown documents without leaving the editor.

The MDflow API requires a Pro plan. Free accounts can sign in but every request returns "Pro plan required".

Features

• Sign in with your browser (OAuth) or a Personal Access Token.
• Tree view in the Explorer: workspaces → folders → documents, loaded on demand.
• Edit documents as normal markdown tabs — Cmd/Ctrl+S saves back to MDflow.
• Full CRUD from the tree's context menus:
  • Workspaces: create, rename, delete.
  • Folders: create, rename, move, delete.
  • Documents: create, rename, move, delete.
• Encryption — encrypt a document's body with a per-file password; edit it transparently. Byte-compatible with the MDflow web app and the mdflow-crypt CLI.

Getting started

1. Install the extension (see Development below to run from source).
2. Open the MDflow view in the Explorer sidebar and click Sign in to MDflow, or run MDflow: Sign In from the Command Palette.
3. Choose how to connect:
   • Sign in with browser — completes an OAuth flow in your browser and returns to VS Code automatically.
   • Paste a Personal Access Token — create a token at mdflow.cz/settings and paste it (mdf_…).
4. Expand a workspace to browse folders and documents. Click a document to open it.

Credentials are stored in VS Code's encrypted Secret Storage — never in settings or on disk in plain text. Sign out with MDflow: Sign Out.

Encryption

Encrypt a document's body with a per-file password. The MDflow server only ever stores ciphertext (mdflow-enc:v1:…); your password and plaintext never leave your machine. It's the same format as the web app and the mdflow-crypt CLI (PBKDF2-600k → AES-256-GCM), so a document encrypted in one opens in the others.

Encryption actions live on the open document — as icons in the editor title bar and in the Command Palette — and only the ones that fit the document's current state are shown:

• Encrypt Document — (plaintext doc) choose a password, entered twice. There is no recovery — save it in a password manager.
• Unlock Document — (encrypted, locked) enter the password to view/edit; handy to retry after a wrong password.
• Lock (Forget Password) — (encrypted, unlocked) forget the cached password; you'll be prompted again next time.
• Remove Encryption — (encrypted) store the body back as plaintext.

Editing is transparent: opening an encrypted document prompts for the password once, then it reads and edits as normal markdown, and Cmd/Ctrl+S re-encrypts. The derived key is cached per document in Secret Storage and cleared on Lock and Sign Out.

The whole body is encrypted verbatim, including any image links (unlike the web app, the extension does not strip images). Encrypted documents are excluded from MDflow search and are opaque to the API and AI agents. There is no password recovery — a forgotten password means the document cannot be decrypted.

Settings

Development

npm install
npm run compile      # or: npm run watch
npm test             # unit tests (API client, PKCE, crypto, key store)

Press F5 in VS Code to launch an Extension Development Host with the extension loaded.

Manual test checklist

These require a real VS Code host and an MDflow Pro account (the automated tests cover the API client and PKCE logic only):

• [ ] OAuth sign-in opens the browser, and after consent the tree populates.
• [ ] PAT sign-in with a valid mdf_ token populates the tree; an invalid token shows an error.
• [ ] Free account → any action shows "Pro plan required" with a settings link.
• [ ] Expand workspace → folders → subfolders and documents appear.
• [ ] Open a document, edit (including non-ASCII), save — reopen confirms the change persisted.
• [ ] Saving a body over 500 KiB is blocked with a clear message.
• [ ] Create / rename / move / delete for a workspace, a folder, and a document; the tree reflects server-returned names.
• [ ] Deleting the last workspace surfaces the server's 409 message.
• [ ] Encrypt Document (password entered twice) → the web app shows the same doc as encrypted; editing + save round-trips; reopening prompts for the password.
• [ ] A document encrypted in the web app opens in VS Code after entering the password (cross-client).
• [ ] Lock re-prompts on next open; a wrong password is rejected and retryable; Remove Encryption restores plaintext.
• [ ] MDflow: Sign Out empties the tree and shows the welcome view (and clears cached encryption keys).

Limitations (v1)

• No offline editing, caching, or conflict resolution — last write wins.
• No sharing management, search, or description editing.
• Single account at a time.
• Loopback OAuth targets desktop VS Code; remote/Codespaces OAuth is untested.

License

MIT