Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 164 additions & 0 deletions DESIGN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
---
name: MSK Paste
description: A web tool of msk-scripts.de. The shop's design system, applied to a paste form and a code view.
colors:
ground: "#f6f6f4"
ground-dark: "#18191b"
card: "#ffffff"
card-dark: "#212225"
tile: "#ededea"
tile-dark: "#111214"
text: "#1c1d1f"
text-dark: "#ececea"
muted-text: "#5a5d61"
muted-text-dark: "#a7a9ad"
msk-green: "#27762e"
msk-green-dark: "#6dbb3d"
band: "#26282b"
band-green: "#7cc04b"
typography:
display: "Archivo Variable, clamp(2.25rem, 1.2rem + 2.4vw, 5rem), 750"
body: "Source Sans 3 Variable, clamp(1.0625rem, 0.9rem + 0.2vw, 1.25rem), line height 1.6"
---

# Design System: MSK Paste

How paste.msk-scripts.de looks and behaves. MSK Paste uses the design system of the MSK
Scripts shop (msk-scripts.de), the same one MSK Forms and MSK Shortener use. The values live in
[`app/globals.css`](app/globals.css); this file says what they are for.

## Principles

**"Paste, then read."** A visitor either pastes something and shares the link, or opens a
link and reads code. The form is the first thing on the home page; on a paste the code is.

- **Structure before looks.** A good-looking page is forgiven small faults, not large ones.
- **One accent.** Anthracite and white carry the page, MSK green marks the brand and what can
be acted on.
- **Fewer boxes.** Groups come from spacing and hairlines. Cards are for the form, the code and
figures.
- **Fluid, not stepped.** Type, spacing and columns grow with the window through `clamp()` up
to UWQHD; components follow their container.
- **Both themes are equal.** Light is the default ground, dark is a palette of its own, the
system setting decides (`next-themes`, `defaultTheme="system"`). Every pair is computed.
- **The CSP is a design constraint.** Scripts run under a nonce (`proxy.ts`). Fonts are local,
code is highlighted on the server, charts are plain bars rendered on the server.

## Exclusion list

Binding for the whole site (decided for msk-scripts.de on 27.10.2026):

- Inter and JetBrains Mono, not even as a fallback.
- The GitHub dark palette, terminal mockups, `>_` icons, green monospace eyebrows with a dash.
- Lucide as the icon set; emoji as icons.
- Rows of three or four equal cards with icon, title and two lines of text.
- Em dashes in visible copy, in both languages.

## Colour

Source tokens are shadcn-style names holding HSL channels (`--primary: 125.3 50.3% 30.8%`),
light in `:root`, dark in `.dark`. `@theme inline` wraps them into utilities
(`bg-primary`, `text-muted-foreground`). Code names the utility, plain CSS writes
`hsl(var(--primary))`.

| Utility | Light | Dark | Role |
|---|---|---|---|
| `background` | `#f6f6f4` | `#18191b` | The ground of every page |
| `card` | `#ffffff` | `#212225` | Cards, the form, the code view, the header bar |
| `muted` | `#ededea` | `#111214` | The tile: hover, code chips |
| `foreground` | `#1c1d1f` | `#ececea` | Text |
| `muted-foreground` | `#5a5d61` | `#a7a9ad` | Secondary text, hints, placeholders |
| `border` | `#dcdcd8` | `#313337` | Hairlines, never text |
| `input` | `#84878b` | `#6d7075` | Field borders, outline buttons (3:1) |
| `primary`, `ring` | `#27762e` | `#6dbb3d` | MSK green: links, the primary fill, focus |
| `primary-hover`, `accent-soft` | derived | derived | Hovered fill; the soft surface of the current item |
| `success`, `warning`, `danger`, `info` | | | Status, always with a word and a sign |
| `band*` | anthracite | same | Page heads and the footer |
| `brand` | `#27762e` | same | The 4 px stripe above the header bar |
| `chart-1` to `chart-5` | | | Chart series |

[`src/test/contrast.test.ts`](src/test/contrast.test.ts) reads the tokens from `globals.css` and
recomputes every rendered pair in both themes (WCAG 2.2 AA: 4.5:1 text, 3:1 controls). Coverage
tests fail when a colour utility has no pair.

## Typography

Archivo (`font-display`) for headings and names, Source Sans 3 (`font-sans`) for everything else,
both variable and loaded locally through `@fontsource-variable` in `app/layout.tsx`. Short codes,
tokens and addresses use the system monospace (`font-mono`); monospace marks what a machine reads.

Sizes: `text-display`, `text-h2`, `text-h3`, `text-lead`, `text-body` (default), `text-small`,
`text-label`. Every maximum is at most 2.5 times its minimum (zoom to 200 %). Running text stays
under 65 characters per line. Figures use `tabular-nums`.

## Layout

- `container-page`: the shell of header, footer and wide pages (statistics), fluid up to UWQHD.
- `tool-column`: the narrower column of the form and the text pages; a paste uses the wider
`container-page`.
- `--space-section` and `--space-stack` set the rhythm between and inside sections.
- No sideways scrolling down to 320 px; the header menu opens below the bar under 1280 px.

## Components

| Component | Use it for |
|---|---|
| `SiteFrame` | Header, the one `<main id="main">`, footer. Every page renders it. |
| `SiteHeader`, `HeaderBar` | The shop's header: green stripe, the tool's own pages, the shop's product lines with Web tools as the current one, the language. |
| `SiteFooter` | The shop's footer on the band: brand, appearance switch, product, ecosystem, legal. |
| `PageHead` | The head of a page on the band: kicker, heading, lead. `size="tool"` on the home page. |
| `Button` | Every button and button-styled link (`asChild`): `primary`, `outline`, `link`, `ghost`, `danger`, `band`, `band-outline`. |
| `ThemeSwitch` | System, light or dark as three toggle buttons. |
| `LanguagePicker` | A native select that posts to `/api/locale` and refreshes. |
| `PasteView` | A paste: title, meta row, actions, the code view with line numbers and wrapping. |
| `StatsCharts` | The most used languages as bars, each value also as text. |

Navigation lives in one table (`src/components/site/navigation.ts`), so the desktop bar and the
menu cannot drift apart. Shop addresses come from `src/lib/shopUrl.ts`.

## Code view

Shiki renders VS Code's Light+ and Dark+ into CSS variables (`defaultColor: false`,
`src/lib/highlight.ts`); `app/globals.css` (`.code-view`) picks the one of the current theme and
puts the code on our card. The few theme colours that miss 4.5:1 on the card are replaced along
their own hue (`CODE_COLOR_REPLACEMENTS`); [`src/test/code-contrast.test.ts`](src/test/code-contrast.test.ts)
checks every colour of both themes, so a Shiki update that changes one shows up there. Line numbers
are drawn by CSS and are not part of the text a visitor copies.

## Icons

Phosphor, regular weight, imported only from [`src/components/icons`](src/components/icons/index.tsx).
Icons are decorative by default (`aria-hidden`); an icon-only button carries its name on the
button. Brand marks (GitHub) are local SVG.

## Motion

Colour and border transitions of 150 ms on controls, 200 ms for fades and the theme colours.
`prefers-reduced-motion` cuts every animation to 0.01 ms.

## Accessibility

- A skip link to the one `<main id="main">`.
- Focus is a 3 px outline in `ring` with 2 px offset; on the band it turns to the band green.
- Targets are at least 44 px (`min-h-11`, `tap-target`).
- Native first: `<select>`, `<dialog>`, real buttons and links.
- Never colour alone: states carry a word and a sign, charts their figures.
- `prefers-contrast: more` raises muted text and lines; `forced-colors` gives controls a system
border.

## Two languages

German and English (`messages/de.json`, `messages/en.json`, next-intl). Every visible string,
`aria-label` included, exists in both. The choice is the `NEXT_LOCALE` cookie; addresses carry no
language. The header and footer texts are the shop's and MSK Forms' wording.

## Adding a colour

Ask first whether an existing token fits. Otherwise add the source token in `:root` (and `.dark`
if it differs), the utility in `@theme inline`, every rendered pair to `PAIRS` in
`src/test/contrast.test.ts`, and a row to the table above.

## Adding an icon

Find it in Phosphor (regular), add it to the import and the export list in
`src/components/icons/index.tsx` in alphabetical order, and import it from `@/components/icons`.
177 changes: 32 additions & 145 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,165 +1,52 @@
# MSK Paste

> A privacy-friendly, self-hosted pastebin alternative — part of the
> [MSK Scripts](https://www.msk-scripts.de) ecosystem alongside
> [MSK Shortener](https://s.msk-scripts.de).

[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE.md)
[![Built with Next.js](https://img.shields.io/badge/Built%20with-Next.js%2015-000000?logo=next.js)](https://nextjs.org)

**Live:** [paste.msk-scripts.de](https://paste.msk-scripts.de)

---
<div align="center">

## ✨ Features

- 📝 **Plain-text pastes** with optional title (up to 1 MB)
- 🎨 **Syntax highlighting** for 30+ languages via [Shiki](https://shiki.style)
- ⏱️ **Expiration** — 10 min · 1 h · 1 d · 1 w · 1 mo · 1 y
- 🔥 **Burn after read** — paste self-destructs after the first view
- 🔒 **Password protection** with bcrypt (cost 12)
- 🔗 **Custom paste IDs** (`paste.msk-scripts.de/my-snippet`)
- 🛠️ **REST API** for CLI / scripting workflows
- 🌍 **Bilingual UI** (German / English) with cookie-based switching
- 📊 **Public stats page** — aggregate numbers only
- 🛡️ **Privacy by default** — no analytics, no GeoIP, IP addresses stored
only as HMAC-SHA-256 hashes

## 🛡️ Privacy & Security
# MSK Paste

- **No tracking, no analytics.** The only third-party script is Cloudflare Turnstile on the create page.
- **Spam protection:** Turnstile, a honeypot, a signed form timestamp, daily limits per address and
content checks (encoded files, link spam, repeats). Scripts need an API key.
- **IPs are never stored.** Rate limiting uses HMAC-SHA-256(ip, secret).
- **Passwords** are stored as bcrypt hashes (cost 12) only.
- **Expired pastes are deleted**, not soft-deleted.
- **Cookies:** exactly one — `NEXT_LOCALE` for the language preference.
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-27762e.svg)](LICENSE.md)
[![Next.js](https://img.shields.io/badge/Next.js-16-black)](https://nextjs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)

See [`/privacy`](https://paste.msk-scripts.de/privacy) for the full policy.
**Self-hosted pastebin with syntax highlighting, expiry and password protection.**

## 🚀 Tech stack
</div>

| Layer | Choice |
|--------------|-----------------------------------------|
| Framework | Next.js 15 (App Router) + TypeScript |
| Database | MariaDB via `mysql2` |
| Styling | Tailwind CSS + MSK design tokens |
| Validation | Zod 4 |
| i18n | next-intl v4 (cookie-based, no prefix) |
| Highlighting | Shiki (server-rendered) |
| Password | bcryptjs |
| Charts | Recharts |
| Hosting | Debian + Apache2 reverse proxy + systemd|
| CI/CD | GitHub Actions (SCP + SSH) |
MSK Paste shares code and text under a short link: highlighted on the server, with an expiry you
choose, an optional password or deletion after the first view, and a delete token instead of an
account. No tracking, no analytics.

Deliberately **not** used: Prisma, Redis, any analytics, any auth provider.
It is part of the MSK Scripts ecosystem and runs at **[paste.msk-scripts.de](https://paste.msk-scripts.de)**.
You are welcome to use it there or to host your own instance.

## 🏃 Quick start (development)
## Quick start

```bash
# 1. Clone & install
git clone https://github.com/MSK-Scripts/msk-paste.git
cd msk-paste
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env: set DB credentials and IP_HASH_SECRET (openssl rand -hex 32)

# 3. Run migrations
cp .env.example .env # database credentials and IP_HASH_SECRET
npm run migrate

# 4. Start the dev server
npm run dev
# → http://localhost:3000
```

For a production deploy on Debian/Ubuntu use the install script:

```bash
curl -fsSL https://raw.githubusercontent.com/MSK-Scripts/msk-paste/main/deployment/scripts/install.sh | sudo bash
```

Details: [`deployment/README.md`](deployment/README.md).

## 📡 REST API

Reading is open. Creating a paste from a script needs an API key, issued by the operator on the
server (see [API keys](#-api-keys)); without one, `POST /api/pastes` only accepts the site's own form.

### `POST /api/pastes`

```bash
curl -X POST https://paste.msk-scripts.de/api/pastes \
-H 'Authorization: Bearer mskp_…' \
-H 'Content-Type: application/json' \
-d '{
"content": "console.log(\"hello world\")",
"title": "My snippet",
"language": "javascript",
"expiresIn": "1w",
"burnAfterRead": false
}'
npm run dev # http://localhost:3000
```

Response:

```json
{
"pasteId": "X7q9bA2k",
"url": "https://paste.msk-scripts.de/X7q9bA2k",
"rawUrl": "https://paste.msk-scripts.de/raw/X7q9bA2k",
"deleteToken": "dk_a7c4f2e1...",
"expiresAt": "2026-05-20T16:00:00.000Z",
"hasPassword": false,
"burnAfterRead": false
}
```

| Method | Path | Purpose |
|----------|-------------------------------|--------------------------------------|
| `POST` | `/api/pastes` | Create a paste (API key required) |
| `GET` | `/api/pastes/:id` | Fetch paste metadata + content |
| `POST` | `/api/pastes/:id/verify` | Verify password, returns content |
| `DELETE` | `/api/pastes/:id?token=…` | Delete a paste with its delete token |
| `GET` | `/api/stats` | Aggregate statistics |
| `POST` | `/api/locale` | Set language cookie (`de` / `en`) |

## 🛠️ Scripts

```bash
npm run dev # Start Next.js dev server
npm run build # Production build
npm start # Start production server on port 3012
npm run lint # ESLint
npm run type-check # TypeScript --noEmit
npm run migrate # Apply DB migrations
npm run cleanup # Delete expired pastes (run via cron)
npm run api-key -- help # Manage API keys (see below)
```

## 🔑 API keys

Only someone with a shell on the server and read access to the app's `.env` can manage keys. A key is
shown once when it is created; the database keeps only a scrypt hash of it.

```bash
/opt/msk-paste/scripts/api-key.sh help # all commands
/opt/msk-paste/scripts/api-key.sh list # id, prefix, label, last use, state
/opt/msk-paste/scripts/api-key.sh create "<label>" # issue a key
/opt/msk-paste/scripts/api-key.sh revoke <key|prefix|id> # block it, keep the row
/opt/msk-paste/scripts/api-key.sh delete <key|prefix|id> # remove it
```
## Documentation

## 📜 License
| Topic | |
|---|---|
| [Features](docs/features.md) | What MSK Paste does |
| [Development](docs/development.md) | Tech stack, local setup, scripts |
| [REST API and API keys](docs/api.md) | Endpoints, examples, issuing keys on the server |
| [Security and privacy](docs/security-privacy.md) | What is stored, spam protection |
| [Design system](DESIGN.md) | Colours, type, layout, the code view |
| [Deployment guide](deployment/README.md) | Apache, MariaDB, systemd, CI/CD |
| [Contributing, support and license](docs/contributing-and-license.md) | Contact, the AGPL in short |

[AGPL-3.0-or-later](LICENSE.md) — if you fork or host MSK Paste publicly,
please share your source code under the same license.
## Help and contributing

## 🙋 Support / contact
Questions and bugs go to the [issue tracker](https://github.com/MSK-Scripts/msk-paste/issues);
security issues as described in [SECURITY.md](SECURITY.md). Contributions are welcome: please open
an issue before larger changes, keep pull requests focused and read [CONTRIBUTING.md](CONTRIBUTING.md).

Author: **Musiker15 — MSK Scripts**
Email: `info@msk-scripts.de`
Website: [www.msk-scripts.de](https://www.msk-scripts.de)
## License

Issues and feature requests → [GitHub Issues](https://github.com/MSK-Scripts/msk-paste/issues)
[GNU Affero General Public License v3.0 or later](LICENSE.md) © [MSK Scripts](https://msk-scripts.de).
If you fork MSK Paste or host it publicly, share your source code under the same license.
15 changes: 5 additions & 10 deletions app/[id]/page.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
import { headers } from 'next/headers'
import { Header } from '@/components/Header'
import { Footer } from '@/components/Footer'
import { SiteFrame } from '@/components/site/SiteFrame'
import { PasteView } from '@/components/PasteView'
import { PasswordPrompt } from '@/components/PasswordPrompt'
import { StatusPanel } from '@/components/StatusPanel'
Expand Down Expand Up @@ -81,15 +80,11 @@ export default async function PastePage({ params }: PageProps) {

function Page({ children, wide = false }: { children: React.ReactNode; wide?: boolean }) {
return (
<main className="min-h-screen flex flex-col">
<Header />
<div className="flex-1 px-6 py-10">
<div className={wide ? 'max-w-5xl mx-auto' : 'max-w-3xl mx-auto'}>
{children}
</div>
<SiteFrame>
<div className={`${wide ? 'container-page' : 'tool-column'} py-[var(--space-section)]`}>
{children}
</div>
<Footer />
</main>
</SiteFrame>
)
}

Expand Down
Loading
Loading