How jhaals/yopass works
1. Overall shape
- Yopass is split into three main deliverables: a Go backend service, a React/TypeScript web app, and a separate Docusaurus-based microsite for docs/marketing. The core product is the backend plus web app; the microsite is mostly informational and licensing-related.
2. Primary runtime: yopass-server
- cmd/yopass-server starts the production server. Its core logic lives in pkg/server, which owns HTTP handling, secret lifecycle, storage abstraction, authentication hooks, logging, metrics, and feature gating.
3. Browser-side encryption is the core security boundary
- The web app encrypts secrets in the browser before upload. The server never sees plaintext secret content; it receives ciphertext and stores it until retrieval or expiration. This is the main trust boundary in the system.
4. Secret creation and retrieval flow
- In website/src/features/CreateSecret.tsx and the display-secret flow, the client generates a key, encrypts the secret locally, and posts the encrypted payload to the server API.
- Retrieval is one-time by default: the user opens a generated URL, the client fetches the ciphertext, decrypts locally, and the server removes or invalidates the stored record after access.
5. Storage backends and expiry
- The backend is storage-agnostic for secret metadata and ciphertext, with Memcached as the default backend and Redis as an alternative. This is implemented through the database/storage layer in pkg/server.
- File uploads are handled separately through file store abstractions (disk, s3, and DB-backed variants), with cleanup logic to enforce expiration and size limits.
6. File sharing is a separate but related pipeline
- File uploads use streaming encryption/decryption paths, so large files do not need to be loaded fully into memory. The server mainly brokers encrypted file blobs and expiration metadata, while the client handles crypto.
7. Feature modules in the backend
- pkg/server contains distinct subsystems for:
- audit logging,
- read receipts,
- secret requests,
- webhook delivery,
- request/response handling,
- OIDC authentication,
- license verification and gated enterprise features.
- These are layered on top of the core secret store rather than replacing it.
8. Authentication and enterprise controls
- OIDC support lets deployments require login and restrict access by email domain. These features are integrated into the server, but are not mandatory for basic anonymous secret sharing.
- Several advanced capabilities are license-gated, including theming/branding, audit logging, read receipts, and webhooks.
9. Client application structure
- The website app is a modular SPA with feature folders for creating secrets, displaying secrets, request/reveal workflows, receipt lists, and read-only mode.
- Shared code covers API access, crypto, auth state, configuration, localization, theming, and request/receipt persistence in the browser.
10. Secondary CLI/library surface
- pkg/yopass and cmd/yopass provide a separate Go client/utility layer built on top of shared Yopass logic. This is distinct from the server and appears to support programmatic or command-line usage of the Yopass flows.
11. Docs, microsite, and checkout flows
- The microsite directory is a separate frontend site for docs and public-facing pages. It also contains checkout/success/canceled routes, which suggests it participates in the licensing or purchase flow for paid features.
- The repository’s docs/ content and the microsite are not part of the secret-sharing runtime, but they are important for deployment, configuration, and feature discovery.
12. Deployment topologies
- The repo supports multiple deployment modes: Docker, Docker Compose, Kubernetes, and AWS CDK.
- The backend can run behind TLS itself or behind a reverse proxy; Memcached/Redis are external dependencies, and optional S3/MinIO or local disk can be used for file storage.
13. Operational concerns
- The server includes logging, metrics, audit trails, and cleanup routines, so the architecture is not just request/response API serving; it also has background expiration and compliance-oriented event recording.
- Webhooks provide outbound notifications for secret lifecycle events, extending the system beyond its own storage boundary.
14. Key diagram boundary
- The most important architectural diagram should show: browser/client encryption and UI on one side, the Go server as the trust-minimized API in the middle, and storage/auth/notification backends as external dependencies on the other side.
Main entry points: server.go Server core · App.tsx SPA shell · crypto.ts Browser crypto · api.ts API client
Components 23
Core runtime
Go server and CLI surfaces that implement secret storage and retrieval.
- Server entry · Starts the production server process.
cmd/yopass-server/main.go - Server core · Owns request handling, feature wiring, and secret lifecycle orchestration.
pkg/server/server.go - Secret store · Abstracts metadata and ciphertext persistence across backends.
pkg/server/database.go - File store · Manages encrypted file blobs and storage backends.
pkg/server/filestore.go - Cleanup job · Enforces expiration, size limits, and file cleanup.
pkg/server/filestore_cleanup.go - OIDC auth · Adds login and domain-based access control.
pkg/server/oidc.go - License gate · Verifies license state and enables enterprise features.
pkg/server/license.go - Audit log · Records security and lifecycle events.
pkg/server/audit.go - Webhooks · Delivers outbound events for secret lifecycle changes.
pkg/server/webhook.go - Streaming path · Handles streaming upload and download flows for large files.
pkg/server/server_stream.go - Yopass lib · Shared client-side Go library for Yopass flows.
pkg/yopass/yopass.go - CLI entry · Command-line utility built on the shared Yopass library.
cmd/yopass/main.go
Web app
Browser application for secret creation, retrieval, receipts, and requests.
- SPA shell · Top-level browser application and routing container.
website/src/app/App.tsx - Browser crypto · Encrypts and decrypts secrets locally before and after transfer.
website/src/shared/lib/crypto.ts - API client · Encapsulates calls to the backend service.
website/src/shared/lib/api.ts - Create secret · Generates keys, encrypts payloads, and submits ciphertext.
website/src/features/CreateSecret.tsx - Decrypt secret · Fetches ciphertext and decrypts it locally in the browser.
website/src/features/display-secret/Decryptor.tsx - Streaming upload · Browser-side upload flow for large encrypted files.
website/src/features/StreamingUpload.tsx - Secret requests · Creates and manages request/reveal workflows.
website/src/features/request-secret/CreateRequest.tsx - Auth state · Tracks login requirements and access state in the UI.
website/src/shared/context/AuthProvider.tsx
Microsite
Docs, public pages, and licensing checkout flows.
Deployment
Packaging and infrastructure entry points.
- CDK stack · Infrastructure deployment definition for cloud setups.
deploy/cdk/lib/cdk-stack.ts
Connections 26
- Server entry → Server core: starts · Bootstraps the HTTP service and configuration.
- Server core → Secret store: stores · Persists ciphertext and secret metadata.
- Server core → File store: brokers files · Routes file-backed secrets to the blob layer.
- Server core → Streaming path: streams · Handles large encrypted file transfer.
- Server core → OIDC auth: auth · Optionally requires login and domain checks.
- Server core → License gate: gates · Enables enterprise-only capabilities.
- Server core → Audit log: logs · Emits audit events for security-sensitive actions.
- Server core → Webhooks: notifies · Sends lifecycle events outward.
- File store → Cleanup job: expires · Cleans up expired files and enforces limits.
- SPA shell → Create secret: routes · Shows the secret creation flow.
- SPA shell → Decrypt secret: routes · Shows the retrieval and decrypt flow.
- SPA shell → Streaming upload: routes · Shows the large-file upload flow.
- SPA shell → Secret requests: routes · Shows request and reveal workflows.
- SPA shell → Auth state: state · Propagates login and read-only status.
- Create secret → Browser crypto: encrypts · Creates keys and ciphertext in the browser.
- Create secret → API client: uploads · Posts encrypted payloads to the server.
- Decrypt secret → API client: fetches · Retrieves ciphertext or file blobs.
- Decrypt secret → Browser crypto: decrypts · Recovers plaintext locally.
- Streaming upload → Browser crypto: encrypts · Streams encrypted file content from the browser.
- Streaming upload → API client: uploads · Sends encrypted file chunks and metadata.
- Secret requests → API client: syncs · Creates requests and updates reveal state.
- Yopass lib → Browser crypto: shares logic · Reuses common Yopass flow primitives.
- CLI entry → Yopass lib: uses · Builds CLI behavior on the shared library.
- Docs site → Checkout: links · Connects docs and marketing pages to licensing flows.
- CDK stack → Server core: deploys · Defines cloud deployment for the backend runtime.
- CDK stack → SPA shell: deploys · Can package the web application as part of infrastructure.