Data Contracts

Data-Contracts.md

Data Contracts

Big Rule

runtime data lives under /data.

repo intent:

  • /data is not supposed to be versioned normally
  • .gitignore ignores /data/**/*
  • .rsyncignore excludes /data/** from deployment sync

so local/dev/prod data has to be managed separately.

data/accounts/

accounts.json

expected top-level shape:

{
  "accounts": [
    {
      "username": "string",
      "name": "string",
      "password": "bcrypt-hash or empty",
      "isAdmin": true,
      "mustResetPassword": false,
      "discordUserId": "optional discord snowflake string",
      "allowedPages": ["feed", "journal", "comments", "chat"],
      "bookmarks": ["2026-01-01_12-00-00", "journal:12"],
      "theme": "default|classic|theme-id",
      "glowIntensity": "none|low|medium|high",
      "mobileFriendlyView": true,
      "onekoEnabled": true,
      "colors": {
        "bg": "#RRGGBB",
        "fg": "#RRGGBB",
        "border": "#RRGGBB",
        "subtle": "#RRGGBB",
        "links": "#RRGGBB"
      }
    }
  ]
}

notes:

  • extra unknown keys can exist and are preserved by account/admin/edit
  • bookmarks are the current source of truth for logged-in users
  • bookmark ids currently use raw feed ids and journal:{id}; legacy newsletter:{id} values can exist but are ignored
  • theme: default is blackprint and uses the base template plus /style.css; theme: classic enables saved colors; any other valid value refers to a /themes/{theme-id}.json file
  • legacy blackprint normalizes to default, custom normalizes to classic, and newsprint normalizes to whiteprint
  • mustResetPassword is used by the shared session bootstrap to force first-login password changes
  • discordUserId links a site account to a Discord member for bot DMs and notifications
  • allowedPages currently includes functional grants like feed, journal, comments, and chat

data/chat/

one-time private conversations live as individual encrypted JSON envelopes:

{
  "version": 1,
  "cipher": "aes-256-gcm",
  "nonce": "base64",
  "tag": "base64",
  "ciphertext": "base64"
}

notes:

  • each file is named {conversationId}.json; new chat ids are 9 lowercase letters/numbers
  • legacy 32-character lowercase hex ids are still accepted so older active links do not break
  • decrypted payloads contain conversation metadata, the recipient label in name, the recipient cookie hash, and message records
  • messages may include an attachment object with encrypted blob metadata: id, name, mime, and size; image/audio/video attachments are served inline through the authorized chat route so they can render or play in the chat UI
  • messages may include replyTo with another message id, plus reactions keyed by valid emoji sequences with active viewer roles such as manager or participant
  • conversations may include participantUsername when a logged-in account claims the invite, or participantHash when an anonymous browser cookie claims it; the first-open popup copy changes based on that claim type
  • conversations may include recipientIntroSeenAt once the recipient has seen the first-open security/help popup
  • recipient cookies are HttpOnly and scoped to /chat
  • the first non-manager account or anonymous browser to open /chat/{conversationId} claims the recipient slot
  • account-linked recipients can delete their own active chat; anonymous cookie-linked recipients cannot
  • admins and accounts with allowedPages containing chat can create, view, and delete conversations without claiming the recipient slot
  • deleting a conversation unlinks the encrypted JSON file immediately
  • encryption uses FRIDG3_CHAT_KEY when set; otherwise the app creates data/chat/.chat_key
  • lightweight presence indicators use sidecar files under data/chat/.presence/{conversationId}.json; current entries store lastSeen, active, and a short-lived typingUntil, while older timestamp-only entries are still readable
  • attachments are encrypted AES-256-GCM envelopes under data/chat/.attachments/{conversationId}/; they are served only through the authorized chat route and are deleted with the conversation
  • attachment uploads are capped at 8 MB

/themes/

theme metadata lives as JSON files directly under /themes.

{
  "name": "Theme Name",
  "html": "template-file.html",
  "css": "stylesheet-file.css"
}

notes:

  • the metadata filename is the saved theme id, for example /themes/cool.json becomes cool
  • name is the label shown in /settings
  • html and css must be relative paths in /themes/lib, for example aero/aero.html and aero/aero.css
  • theme asset paths cannot be absolute, contain .., or use characters outside letters, numbers, ., _, -, and /
  • desktop rendering uses both themed HTML and CSS
  • mobile rendering keeps template_mobile.html and only swaps the CSS

login_attempts.json

  • map of client IP -> unix timestamp array
  • used for login throttling

data/feed/

feed post format:

  1. @username
  2. YYYY-MM-DD HH:MM:SS
  3. body text / BBCode

other file:

  • index.toml is generated by /feed/index.php

feed bodies can include public voice notes as BBCode:

[audio=/data/audio/voice/example.m4a][name:voice-note.m4a]

voice notes are created from temporary [voice:N] editor placeholders, verified at upload time, transcoded to small mono .m4a files, and stored under data/audio/voice/.

data/feed/replies/

per-post replies live in {postId}.json files shaped roughly like:

{
  "replies": [
    {
      "id": "20260413153000_deadbeef",
      "username": "toast",
      "date": "2026-04-13 15:30:00",
      "body": "reply body with BBCode"
    }
  ]
}

notes:

  • reply ids are generated on write; older data may be normalized into legacy_* ids at read time
  • reply bodies can contain image BBCode that points at /data/images/*
  • new reply bodies can also contain voice note audio BBCode that points at /data/audio/voice/*

data/journal/

published journal post:

  1. YYYY-MM-DD
  2. title
  3. description
  4. trusted HTML body

draft format:

  1. USER:<username>
  2. title
  3. description
  4. optional FORMAT:html
  5. draft body

without FORMAT:html, preview treats the body as BBCode. with it, preview treats the body as raw HTML.

data/guestbook/

entry format:

  1. timestamp
  2. display name
  3. message body

plus:

  • ip_index.json for one-post-per-IP ownership tracking

data/images/

  • uploaded images used across feed, journal, and gallery content
  • expected web path is /data/images/<filename>

data/music/

artist folders currently include:

  • frdg3
  • cactile

album JSON shape:

{
  "album_name": "string",
  "album_caption": "string",
  "album_type": "Album|EP|Single|Remix|...",
  "album_art": "/data/images/example.jpg",
  "album_art_directory": "/data/images/example.jpg",
  "order": 6,
  "songs": [
    { "name": "Track", "directory": "/data/audio/file.wav" }
  ]
}

album_art_directory is preferred by current code.

data/audio/

  • track files referenced by music metadata
  • also used by shared playback features
  • data/audio/voice/ stores public feed voice notes as compressed .m4a files

data/contact/

  • private contact submissions as {YYYYMMDDHHMMSS}_{random}.json
  • each submission stores id, createdAt, hashed IP, user agent, name, email, message, notification channel id, and optional notifyError
  • rate_limits.json stores hashed client IP keys mapped to recent submission timestamps for throttling
  • nginx blocks direct web access to this directory; submissions are only shown through the admin-only /contact?dashboard=1 route

data/mdpaste/

  • temporary markdown paste records as {id}.json
  • ids are 16 lowercase hex characters
  • records expire after 30 days and are cleaned up opportunistically on create/view
  • unencrypted records store a markdown string
  • encrypted records store only AES-256-GCM ciphertext plus PBKDF2-SHA256 salt/nonce/tag metadata; the password is never stored
  • hard_breaks controls whether single paragraph newlines render as <br> instead of spaces

data/etc/

wip

  • plain text maintenance flag

webhooks.json

used key:

{
  "discord_feed": "https://discord.com/api/webhooks/..."
}

toast.json

expected shape:

{
  "bot": { "token": "...", "client_id": "...", "status": "online|offline" },
  "stream": { "url": "http(s)://...", "name": "..." },
  "channel": { "id": "...", "name": "..." },
  "features": { "auto_play": true, "loop": true }
}

toast-updates.json

  • array of timestamped bot status entries

toast-feed-notify-state.json

  • internal bot dedupe state for sent feed mention/reply notifications
  • stores which feed mentions and replies have already triggered DMs

toast-dm-history.json

  • tracked inbound/outbound DM threads used by /others/toast-discord-bot/messages
  • stores per-user profile snapshot data plus message history

contact notification endpoint

  • the toast bot exposes localhost-only POST /contact/notify on 127.0.0.1:8765
  • /contact calls it after saving a submission
  • toast sends the alert to Discord channel 1503931489560301609

off-topic-archive.json

  • Discord export blob used by the archive viewer

page_views.json

shape is roughly:

{
  "pages": {
    "/": {
      "count": 12,
      "visitors": {
        "<sha256>": 1730931224
      }
    }
  },
  "updated_at": "2026-03-02T00:00:00Z"
}

data/downloads/

  • downloadable binaries, archives, presets, and similar files linked from the site
...