Skip to main content

​
KeylessSSL architecture overview

​
Repository structure

KeylessSSL is a pnpm workspace with three deployed applications and one shared UI package: The API entry point constructs the Express app, initializes observability, starts background workers, and listens on port 8080.

​
Request and certificate flow

  1. A signed-in user or scoped API key creates a domain.
  2. The API stores the domain under the caller’s organization and returns a unique ownership TXT record plus a delegated-validation CNAME.
  3. Verification performs live TXT lookup for the organization-specific token. It also checks the CNAME and atomically claims the apex for one organization.
  4. Issuance is allowed only for a verified domain whose apex is not claimed by another organization.
  5. The certificate provider creates or reads a Cloudflare for SaaS Custom Hostname and maps Cloudflare hostname and SSL states to active, pending, or error.
  6. Certificate and domain rows retain provider identifiers and status. The sync route refreshes those rows from Cloudflare.
Cloudflare-managed certificates normally do not expose PEM bundles or private keys through KeylessSSL. The bundle route returns content only if the database record contains a PEM bundle.

​
Authentication and authorization

Production configuration requires the Auth0 backend-for-frontend integration. The browser begins Authorization Code with PKCE; the API exchanges the code, verifies the identity token, creates or finds the user and organization, and issues a 12-hour KeylessSSL session token. The /v1 API guard accepts either that session token or an active, unexpired KeylessSSL API key. API-key routes enforce scopes. State-changing resource routes allow interactive owners, admins, and operators, while read-only members remain read-only. Organization, billing, team, profile-security, and API-key administration routes require interactive-user roles as defined by their handlers.

​
Data model

PostgreSQL migrations define these main groups:
  • Identity and tenancy: users, organizations, and organization_members.
  • Domain control: domains plus globally unique apex_claims for tenant-bound ownership.
  • Certificates: certificates, including Cloudflare provider IDs, provider status, validation records, and optional stored bundle fields.
  • Credentials and notifications: api_keys, webhooks, and webhook_deliveries.
  • Traceability and workflow: audit_events, clients, verification_links, and idempotency_keys.
  • Supporting operations: email verification and delivery tables, email suppression, billing columns, durable rate-limit counters, and schema migrations.
Every domain, certificate, API key, webhook, client, verification link, and audit event query in the primary routes is scoped by organization ID.

​
Runtime configuration

The API needs a PostgreSQL database, session and API-key protection secrets, webhook signing secrets, Cloudflare for SaaS access, and Auth0 settings before it starts in production. The portal needs the API base URL and its OIDC client settings. Configuration is supplied by the deployment environment; no credential values or setting names are published here. Other implemented configuration covers public URLs, CORS origins, DNS verification mode, rate limits, webhook retries, email delivery via Resend, Stripe billing, Sentry, and PostHog. Production forces live DNS verification even if a bypass value is configured. Required production services: PostgreSQL, Auth0, Cloudflare zone keylessssl.dev with SaaS Custom Hostnames enabled, Stripe account with configured prices, Resend for transactional email, and stable public URLs for keylessssl.dev, app.keylessssl.dev, and api.keylessssl.dev.

​
Billing and plan limits

KeylessSSL uses Stripe for subscription management with two plans: Domain creation and team invites enforce plan limits at the API level. Rate limiting is per-client-IP (default 120 requests per minute across /v1 routes) and is not tiered by plan.

​
Certificate operations

Certificate operations call the Cloudflare API for the configured zone. No per-hostname origin, SNI, CA, bundle, or TLS extras are sent to Cloudflare.