Skip to content

About

1time-view allows secure sharing of one-time view notes

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

One-Time Secrets

Self-hosted, browser-encrypted text messages with at most one retrieval. Development version 0.2.0-alpha.1.

The browser creates a random 256-bit key and encrypts the message using AES-256-GCM. The API stores ciphertext and public metadata. The complete share link contains the retrieval token and decryption key after #; the browser sends only the token when the recipient explicitly selects Reveal message.

Run with Docker

From the extracted project root, with Docker Engine and the Compose plugin installed:

cp docker/.env.example docker/.env
docker compose --env-file docker/.env -f docker/compose.yml up --build -d
docker compose --env-file docker/.env -f docker/compose.yml ps

Open http://localhost:3000 on the Docker host. The port binds to 127.0.0.1 by default. From another machine, use an SSH local-port forward or configure HTTPS through your reverse proxy; plain HTTP on a LAN hostname/IP does not provide the secure browser context required by Web Crypto.

For an existing host-installed HTTPS proxy:

  1. Set PUBLIC_ORIGIN=https://secrets.example in docker/.env, replacing the hostname and omitting the trailing slash.
  2. Keep the container port on loopback. Use the examples in docker/nginx.conf and docker/nginx-proxy.conf, adapting certificate paths and hostname to your deployment.
  3. Trust only the actual proxy source address observed by the container if per-client IP rate limiting is needed; TRUST_PROXY is empty by default. With Docker port forwarding, this may be a bridge-gateway address rather than 127.0.0.1.
  4. Recreate the application after configuration changes:
docker compose --env-file docker/.env -f docker/compose.yml up -d

The container runs as UID/GID 1000, drops Linux capabilities and has a read-only root filesystem. The notes named volume is writable for SQLite. New volumes inherit the image's /data ownership; existing/bind-mounted directories must be accessible to UID 1000. One application instance, local storage only.

Docker was unavailable in the implementation environment. The Dockerfile and Compose configuration are supplied; the image build, container health and Nginx example have not been run here. CI defines a real container build/smoke/vulnerability gate for a Docker-enabled runner.

Admin dashboard — separate port

The admin dashboard runs at http://localhost:3001; the public app remains on 3000. It shows aggregate message counts, expiry backlog, storage/disk capacity, request statistics and cleanup/runtime health. It is read-only and never lists message contents, keys or share tokens.

After starting Docker, retrieve the server-generated admin credential locally:

docker compose --env-file docker/.env -f docker/compose.yml exec -T app cat /data/admin-token

Paste it into the dashboard's access-token field. The token is generated privately at startup, persists in the data volume and is never printed automatically. Both host bindings default to loopback. Use the exact configured origin; remote admin access needs a tunnel or private HTTPS endpoint. See admin setup, configuration and rotation.

Run directly

Node.js 24.15 or later in the Node 24 line is required; implementation checks used 24.22.1. The backend uses node:sqlite, not an external SQLite service or native npm database module.

npm ci --ignore-scripts --no-audit --no-fund
cp .env.example .env
npm run dev

npm run dev builds and loads .env; it does not install a file watcher. npm start runs an existing build and reads the process environment only. Use HTTPS for non-localhost origins. If you change the port, update PUBLIC_ORIGIN to match exactly.

Behaviour and limits

  • Plain text only: 1–65,536 UTF-8 bytes, including multiline text and Unicode.
  • Unopened expiry: 5 minutes, 1 hour, 24 hours or 7 days; default 24 hours.
  • Opening a link shows confirmation. A GET, HEAD or prefetch cannot consume it.
  • Consumption commits before delivery. A connection failure or an incorrect key can lose the message.
  • Unknown, consumed and expired messages share the same public unavailable response.
  • No accounts, passwords, PBKDF2, attachments, email notifications, per-note analytics or browser storage. Aggregate service counters are available only through the authenticated admin interface.
  • No recovery endpoint, replay cache or second read. Recipients can still copy or screenshot text.
  • Both share-link fields are secrets/capabilities. Anyone with the full link can reveal it while available.

Encryption protects a database copy without the key. It does not protect against an operator replacing the served JavaScript, malware on an endpoint or the messaging provider receiving the complete link. See SECURITY.md.

Data and backups

Exclude the live note volume from backups/snapshots. Restoring an old database can revive consumed links. Back up code and configuration instead; start with an empty note store after data-loss recovery. See operations before changing storage or rolling back.

Normal restarts retain outstanding notes and the current database. Do not remove volumes to restart. Logical deletion does not guarantee forensic erasure from WAL, storage or external snapshots.

Checks

npm run check
npm run audit

check performs TypeScript checking, ESLint, Prettier and the Node unit/integration suite. Playwright is deliberately excluded at the owner's request; see EX-001.

On Linux x86_64, install semgrep==1.183.0 in a Python environment and run bash scripts/security.sh. It downloads checksum-verified Gitleaks 8.30.1 and runs blocking secret detection plus five project-specific SAST rules. See testing for scope and the opt-in browser command.

Source layout

Directory Purpose
public/ HTML shells, CSS and local favicon
admin/ Separate admin HTML and CSS
src/admin-client/ Admin dashboard browser module
src/client/ Browser encryption, link parsing, API adapter and UI
src/shared/ Versioned protocol and validation
src/server/ Configuration, HTTP boundary, lifecycle and SQLite repository
migrations/ Versioned SQLite schema
tests/ Unit/integration tests, public fixtures and disabled-by-default browser suite
docker/ Dockerfile, Compose, environment and proxy examples
docs/ Engineering, security exception, testing, operations and verification evidence

The public listener serves only dist/public/; the separate admin listener serves dist/admin/. Build output, dependencies, environment files and runtime data are excluded from source archives/version control. No licence is granted by this initial implementation; the owner should choose licensing before public distribution.

This is a development alpha. Browser verification, Docker execution, hosted CI/branch-protection verification and human T2 release approval remain outstanding. No deployment has been performed.

About

1time-view allows secure sharing of one-time view notes

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages