Skip to content

authentication.md

Latest commit

 

History

History
49 lines (35 loc) · 1.79 KB

authentication.md

File metadata and controls

49 lines (35 loc) · 1.79 KB

Authentication

Authentication is optional and only applies in serve mode.

Setup

  1. Start server with auth enabled: 
    koshelf serve -i ~/Library --data-path /path/to/runtime-data --enable-auth
  2. On first run, KoShelf generates a password and prints it once.
  3. Rotate password anytime via: 
    koshelf set-password --data-path /path/to/runtime-data --overwrite

set-password Command

Use set-password to initialize, rotate, or replace the serve-mode password:

koshelf set-password [--data-path <PATH>] [--password <VALUE> | --random] [--overwrite]
  • Without --password, KoShelf prompts interactively
  • With --random, KoShelf generates a password and prints it once
  • --password and --random are mutually exclusive
  • Password length must be 8-1024 characters
  • Data path resolution order: --data-path > KOSHELF_DATA_PATH > config file
  • Without --overwrite, command is idempotent (no-op if a password already exists)

Examples

# Prompt interactively and replace existing password
koshelf set-password --data-path ~/koshelf-data --overwrite

# Set explicit password (avoid shell history for sensitive values)
koshelf set-password --data-path ~/koshelf-data --password 'correct horse battery staple' --overwrite

# Generate a random password and print it once
koshelf set-password --data-path ~/koshelf-data --random --overwrite

Protected Routes

Protected routes include /api/** (except GET /api/site and POST /api/auth/login) and runtime assets under /assets/** (including /assets/covers/**, /assets/files/**, and /assets/recap/**). Shell assets under /core/** remain public.

Authentication is not available in static export mode (koshelf export), so any hosted static files are governed by your hosting setup.