Security model
Threat model in one paragraph
An attacker may: hold a valid account in another tenant, steal a public SDK key from a shipped app, intercept or replay update traffic, tamper with stored artifacts, or compromise a CI secret. Stacklift is designed so that none of these lets them read another tenant's data, publish an update to devices, or deliver an unsigned/altered artifact.
Authentication
- Passwords: scrypt (N=16384) with a per-password salt. Login performs a hash comparison even for unknown accounts and returns an identical error.
- Sessions: 15-minute JWT access tokens (kept in memory by the web app) + 30-day rotating refresh tokens in an
HttpOnly,SameSite=Laxcookie. Reusing a rotated refresh token revokes the whole token family. - Email verification and password reset tokens are random, stored as SHA-256, single-use (atomic claim) and expire. Resetting a password revokes all sessions.
- Google and GitHub sign-in go through Firebase Authentication, which only proves identity. The dashboard sends the Firebase ID token to
POST /auth/firebase; the API verifies its signature against Google's published keys, its issuer and audience (our Firebase project) and its expiry, and accepts onlygoogle.comandgithub.comsign-ins (email/password tokens are refused). Accounts are matched by the provider's own account id and linked by email only when the provider vouches the address is verified. Stacklift then issues its own session; the browser signs out of Firebase immediately, so no Firebase session is kept. Inert untilFIREBASE_PROJECT_IDis set. - Rate limiting: global per-client limit and a stricter limit on credential endpoints.
Authorization and tenant isolation
- Every org-scoped route resolves the organization and the caller's membership in one guard. A non-member gets 404, so existence isn't disclosed.
- Project ids are looked up *inside* the resolved organization. A project, release, channel or rollout id from another tenant can't match, even with a valid org in the URL.
- RBAC permissions are defined once in
@stacklift/shared(ROLE_PERMISSIONS). A project membership can only elevate a role. - Ownership rules: only owners grant/alter ownership; an organization always keeps at least one owner; invitations only work for the invited, verified email.
- All org-owned tables carry
orgId(denormalised on purpose) so a query can always be constrained by tenant.
Credentials
| Credential | Format | Storage | Can do |
|---|---|---|---|
| Personal access token | slp_<prefix>_<secret> | SHA-256 of secret | Acts as the user (CLI) |
| Project public key | slk_… (type PUBLIC) | SHA-256 | updates:check, updates:report only |
| Project secret key | slk_… (type SECRET) | SHA-256 | One project, scoped (CI) |
Secrets are shown once and never returned again. Keys can be rotated (optionally with a grace period) and revoked; revocation takes effect within 15 seconds on the delivery plane (auth cache TTL) and immediately on the control plane.
Artifacts and signing
- Uploads use signed, expiring, size-bound URLs straight to object storage. Keys are tenant-prefixed and content-addressed.
- The control plane recomputes SHA-256 and size from the stored object; client-declared values are never trusted. Mismatch → artifact and release fail, the object is deleted.
- Each project has an Ed25519 key pair. The private key is encrypted with AES-256-GCM (
KEY_ENCRYPTION_SECRET) and never leaves the API. The signature covers checksum, size, release id, version, platform, runtime version and kind, so an artifact can't be replayed as another release. - Clients verify size, checksum and signature before applying, and should pin the public key.
- Layouts (
ui-layout) are data, never code, and are validated on the server before signing: known components only, https-only links, at most 512 KB, 32 levels, 2000 components and 500 list items, and bindings that read only the data's own properties (never the prototype chain). Every renderer enforces the same limits again, and a layout it cannot draw is never applied. - Scripts (
script-bundle) run in an interpreter with no network, file or timer access, and can call only the functions the app registers. - With the local storage driver, uploads go to a receiver authorised by a signed, expiring, size-capped token. Body parsers are disabled on that route, so the bytes are streamed to disk exactly as sent.
- Replace
CryptoServicewith a KMS-backed implementation to keep key material in an HSM — that boundary is deliberate.
Webhooks
HMAC-SHA256 over timestamp.body, replay window enforced by the receiver, SSRF guard on targets, no redirects, secret encrypted at rest.
Operational
- Strict zod validation on every body/query; unknown fields stripped.
helmetheaders, CORS allow-list, 1 MB JSON limit, uniform error envelope that never leaks internals.- Audit log for membership, project, release, deployment, rollout, rollback, key and integration changes.
- Idempotency keys on deployments; BullMQ jobs are retried with exponential backoff and handlers are idempotent.
- State changes that must be atomic (deploy execution, rollback, rollout completion) run in a database transaction with row locks.
Known gaps (tracked in the roadmap)
- No SSO/SCIM, no 2FA yet.
- Billing/plan limits are not enforced.
- The
localstorage driver is for development; use S3-compatible storage + CDN in production. - Telemetry (
UpdateEvent) lives in Postgres; very large fleets should move it to a columnar store behind the same API.