Markdown

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=Lax cookie. 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 only google.com and github.com sign-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 until FIREBASE_PROJECT_ID is 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

CredentialFormatStorageCan do
Personal access tokenslp_<prefix>_<secret>SHA-256 of secretActs as the user (CLI)
Project public keyslk_… (type PUBLIC)SHA-256updates:check, updates:report only
Project secret keyslk_… (type SECRET)SHA-256One 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 CryptoService with 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.
  • helmet headers, 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 local storage 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.