Skip to main content

Security overview for reviewers

This page is for security and IT reviewers. It describes how vastframe isolates organizations from each other, how identity flows between components, and how secrets are stored. Each section notes what is built today and what is planned for Azure installations.

Deployment models​

ModelWhat it is
Self-hostedvastframe runs in your own Azure subscription. The installation serves exactly one organization (the default tenant).
vastframe cloud (SaaS)One shared Hub serves many organizations. Each organization is a tenant with its own domain, for example acme.vastframe.app.

Both run the same code. Self-hosted is the SaaS code with one tenant.

Availability

The platform is built and tested end to end on a local stack. Several Azure components (Container Apps, Key Vault, managed identities, Microsoft Graph on-behalf-of, Bot Framework, Azure Cost Management) are drivers with planned Azure implementations. This page calls them out where they matter.

Tenant isolation​

Isolation between tenants is enforced by PostgreSQL, not only by application code.

  • Tenant column and forced row-level security. Every tenant-owned table in the Hub database has a tenant_id column (defaulting to the session's tenant) and forced row-level security.
  • A non-owner role. The Hub's API and worker query as a role that doesn't own the tables and has no BYPASSRLS, so the policies always apply.
  • Tenant set per query. The database pool sets the tenant from the caller's request scope before every query. A query outside any tenant scope sees no rows.
  • Owner connection only where needed. The table owner connection is used only for migrations, the tenant registry, sign-in settings and the installation API.
  • Few global tables. Only the tenant registry, tenant domains, tenant identity-provider settings, verified email domains, licences, the installation record and signing keys are global. The Hub's app role can read but not change the tenant tables.

Where a request's tenant comes from​

  1. The host name. Each tenant has one or more domains, matched by longest suffix (console.acme…, <app>.acme…, auth.acme…).
  2. X-TC-Tenant, used by the CLI, MCP and internal callers that call the Hub API directly.
  3. The installation default, which is empty on the SaaS Hub: a request that names no tenant is refused there.

Background jobs carry their tenant and run inside it. In-memory caches (access decisions, role lookups, database pools, gateway and storage caches) are keyed by tenant.

Per-tenant resources​

ResourceSelf-hostedSaaS tenant acme
App containers and imagestc-<project>-<id>tc-acme--<project>-<id>, labelled with the tenant
App database and rolesp_<project>p_acme__<project>
Storage containertc-<project>tcacme-<project>
Token audiencestc:hub, tc:app:<project>tc:hub:acme, tc:app:acme:<project>
Edge session cookieOn the installation's apps domainOn the tenant's domain (for example acme.vastframe.app), marked with the tenant, ignored on other tenants

Each project gets its own PostgreSQL database on a separate app database server that holds app data only, not on the Hub database.

Identity and tokens​

  • Sign-in happens only at the Edge: OpenID Connect authorization code flow with PKCE and a nonce against the organization's own identity provider, WorkOS SSO (authorization code with state), or one-time email links. See Sign-in & identity.
  • Sessions are encrypted cookies (8 hours by default), bound to the tenant they were created in. Each has its own id, and sign-out is enforced on the server: signing out ends that session everywhere (a copied cookie stops working), and an Org Admin can sign a person out everywhere from Admin › People. Turning an account off ends its sessions at once.
  • Emails count only when verified. A person is matched by email, or auto-joins on a verified domain, only when the identity provider vouches for the address (email_verified) or the person opened an email link.
  • Apps receive a signed user token (X-TC-User): ES256, 5-minute lifetime, audience bound to one project. The Edge strips any client-supplied copy. See Verify the user's identity.
  • Audiences separate every consumer: apps (tc:app:…), the Hub API (tc:hub…) and the Integration Gateway for background services (tc:gateway). A token for one isn't accepted by another.
  • Background services use a project token accepted only by the gateway: valid for 1 hour for each cron run, and 30 days for long-running workers (minted when the worker container starts).
  • Databases: the Data API runs every signed-in user's queries as a shared tc_user role, so the project's row-level security policies apply. Which rows a user sees depends on the policies the app defines.
Availability

The Hub signing key is stored in the Hub database today; Key Vault is planned. A managed (workload) identity per project, replacing the project token, is planned for Azure. The OAuth authorization server for the CLI and MCP is not built yet; they still authenticate with a development token.

Secrets at rest​

SecretProtection todayPlanned on Azure
Project environment variables and secretsAES-256-GCM, key derived (HKDF) from an installation key; each ciphertext is bound to its project and variable name, so a copied value won't decrypt elsewhere. Secrets are write-only: no API, CLI or MCP response returns them.Key Vault or Container Apps secret references
Users' OAuth tokens (for example Salesforce)AES-256-GCM in the Hub database, with one installation-wide key (TC_SECRETS_KEY)Key Vault
Org credentials (for example an ERP service account) and OAuth client secretsAES-256-GCM with the same installation key; shown masked (••••1234) in the console; apps never see them (the gateway uses them)Key Vault
Identity-provider client secrets for a tenantEncrypted (AES-256-GCM, bound to the organization) in the tenant's sign-in settings, a global table only the owner connection can write; never sent back to the browserKey Vault reference

Integration controls​

  • Apps never hold vendor credentials. Every call goes through the Integration Gateway, which checks the project's grants on each call.
  • The gateway's allowlist is closed by default: unknown Microsoft Graph paths, SOQL sub-queries and SQL writes are refused before any grant check.
  • Delegated integrations act with the signed-in user's own vendor permissions, so a user only sees what they could already see in the vendor's app.
  • Every call is audited. See Integrations.

Storage​

  • Files are served on the app's own host, behind sign-in and the app's access check. There's no anonymous public option.
  • Uploads are sniffed; HTML, SVG, XML and JavaScript are refused because files are served from the app's own origin. Downloads use nosniff and a sandbox content security policy.

Governance​

  • Every app has an owner, an expiry under the lifecycle rules, and a kill switch.
  • When an owner is disabled or removed from the directory, the lifecycle job moves their projects to the nearest active manager. If there is none, Org Admins are told.
  • Every change is written to the audit log.

Known limits​

  • Used one-time sign-in links are remembered in the Edge's memory, so the Edge runs as a single replica for now.
  • Teams card callbacks are verified with a shared HMAC secret today; Bot Framework token validation is planned for Azure.
  • Per-tenant wildcard certificates on Azure are not set up yet.
  • Local builds run on the Docker daemon without a sandbox.
Was this page helpful?