File Format

Claspt stores everything as plain files in a regular directory. No proprietary database, no opaque binary format. This page documents the structure so you know exactly what’s on disk.

Vault Directory Structure

~/Claspt/
  general/                     — default folder
  credentials/                 — suggested folder (created on first use)
  _media/                      — image and file attachments
  .securenotes/
    config.json                — vault configuration
    vault.key                  — encrypted master key (NEVER synced)
    index/                     — tantivy search index (local only)
    license.token              — Pro license (Ed25519 signed)
    sync.json                  — sync configuration
  .git/                        — auto-initialized for version history

• Top-level folders are user-created categories (e.g., general/, credentials/, work/).
• _media/ stores images and attachments referenced by pages.
• .securenotes/ contains internal state. It’s excluded from markdown rendering but included in sync (except vault.key and index/).
• .git/ is auto-initialized when you create the vault. Claspt auto-commits on save.

Page Format

Each page is a standard markdown file with YAML frontmatter:

---
id: a1b2c3d4-5678-90ab-cdef-1234567890ab
title: AWS Production Keys
created_at: 2026-01-15T10:30:00Z
updated_at: 2026-03-22T14:15:00Z
pinned: false
archived: false
tags: [aws, production, deploy]
folder: credentials
encrypted: false
---

# AWS Production Keys

Account ID: `123456789012`

:::secret[Access Key ID]
enc:v1:c2VjcmV0IGtleSBnb2VzIGhlcmU=...
:::

:::secret[Secret Access Key]
enc:v1:YW5vdGhlciBzZWNyZXQga2V5...
:::

Last rotated: 2026-03-01

Frontmatter Fields

Field	Type	Description
id	UUID v4	Unique page identifier, generated on creation
title	string	Page title (also used in search)
created_at	ISO 8601	Creation timestamp
updated_at	ISO 8601	Last modification timestamp
pinned	boolean	Whether the page is pinned to the top of the list
archived	boolean	Whether the page is archived (hidden from default view)
tags	string[]	Tags for categorization and search
folder	string	Parent folder name
encrypted	boolean	Whether the entire page body is encrypted

Filename Convention

YYYY-MM-DD-HHMMSS-title-slug.md

Example: 2026-01-15-103000-aws-production-keys.md

The timestamp is the creation time. The slug is derived from the title (lowercased, spaces replaced with hyphens, special characters stripped).

Secret Block Format

Secret blocks use the :::secret fenced directive:

:::secret[Label]
enc:v1:<base64-encoded-ciphertext>
:::

• Label — plaintext, searchable, visible even without unlocking.
• Value — AES-256-GCM ciphertext, Base64-encoded.
• enc:v1: prefix — version marker for the encryption format.

The ciphertext includes the 96-bit nonce prepended to the encrypted data, so each block is self-contained.

Note

When you create a new secret in the editor, the plaintext value is visible until you save. On save, Claspt encrypts it and replaces the plaintext with enc:v1:.... The .md file on disk never contains plaintext secret values.

Full-Body Encrypted Pages

When encrypted: true is set in the frontmatter, the entire page body (everything below the frontmatter) is a single enc:v1:<base64> blob:

---
id: ...
title: Top Secret Project
encrypted: true
---
enc:v1:bG9uZyBlbmNyeXB0ZWQgYmxvYiBnb2VzIGhlcmUuLi4=

The title remains plaintext for navigation. Everything else is encrypted.

vault.key Format

The vault.key file contains the encrypted master key:

[1 byte: version] [16 bytes: salt] [AES-256-GCM encrypted master key]

• Version byte — currently 0x01.
• Salt — random, used with Argon2id to derive the password key.
• Encrypted master key — 256-bit key encrypted with the password-derived key.

Caution

vault.key is never synced. Each device generates its own vault.key when you enter your master password for the first time. If you lose this file and forget your password, your secrets are unrecoverable.

config.json

Vault-level preferences stored in .securenotes/config.json:

{
  "version": 1,
  "auto_lock_timeout": 300,
  "theme": "system",
  "editor": {
    "font_size": 14,
    "line_numbers": false,
    "word_wrap": true
  }
}

This file syncs across devices, so your preferences follow you.

Portability

The entire vault directory is portable:

• Copy it to a USB drive, another machine, or a cloud folder.
• Open the .md files in any text editor — you’ll see full markdown with encrypted ciphertext for secrets.
• Import into another Claspt installation by pointing it at the directory and entering your master password.

Tip

Because pages are plain markdown, you can use standard unix tools (grep, find, wc) on your vault. Secret values will show as enc:v1:... ciphertext, but everything else is human-readable.