Cryptographic Key Management & Envelope Encryption
Enterprise-grade multi-tenant envelope encryption, platform root keyring rotation, AAD ciphertext binding, and zero-downtime database rewrap.
When storing confidential or secret custom fields — such as tax identifiers, biometric tokens, banking details, or security clearances — SCRIPE applies hardware-grade envelope encryption. Every value is protected using AES-256-GCM with tenant-unique cryptographic keys derived via HKDF-SHA256 from the active platform root keyring. Ciphertext cannot be forged, cannot be decrypted under another tenant or entity, and can be safely rewrapped across key rotations with zero downtime.
Core cryptographic architecture
The encryption subsystem is structured across five resilient security layers:
Multi-version root keyring
Active platform key for new writes alongside a catalog of retained historical keys for seamless zero-downtime reads.
Tenant HKDF derivation
Tenant-isolated secret keys derived deterministically using HKDF-SHA256 with tenant code salt and application info tags.
Binary Magic Frame v2
Compact binary header encoding version, platform key ID, tenant version, 96-bit nonce, and 128-bit authentication tag.
Cryptographic AAD binding
Ciphertext is mathematically bound to TenantId, EntityId, and FieldDefinitionId preventing cross-entity injection attacks.
Live DB rewrap migration
Background worker iterates through database records using cursor batching to re-encrypt data under new keys without locking tables.
Unified CLI & Studio ops
Full operational tooling via `scripe crypto` and the SCRIPE Studio visual developer dashboard.
Dual-Envelope Split-Key Derivation
SCRIPE enforces a zero-knowledge cryptographic separation between platform operators and tenant data using a split-key envelope hierarchy:
| Key Component | Storage & Custody | Cryptographic Responsibility |
|---|---|---|
| Platform Master KEK | Host Environment / KMS (`.env`) | Root Key Encryption Key (KEK). Encrypts tenant secrets at rest. Platform operators cannot read tenant data without tenant secrets. |
| Tenant Cryptographic Secret | Tenant Database (`EncryptedTenantSecret`) | Unique 256-bit CSPRNG secret generated per tenant. Stored encrypted under active Platform KEK. |
| Derived Data Encryption Key (DEK) | Ephemeral Memory Only (HKDF) | Derived at runtime via HKDF-SHA256 from XOR of Platform Key and Tenant Secret. Never persisted to disk. |
| Contextual AAD Tag | AES-256-GCM Envelope | Cryptographically binds ciphertext to TenantId, EntityId, and FieldId, preventing cross-entity and cross-tenant replay attacks. |
Binary Magic Frame v2 wire specification
Encrypted values are persisted as compact base64-encoded binary frames that adhere to the v2 specification:
| Byte Offset | Header Field | Length | Cryptographic Purpose |
|---|---|---|---|
| Byte 0 | Version Header | 1 Byte | Magic Frame version byte (0x02 for v2 authenticated frames). |
| Bytes 1–4 | Platform Key ID | 4 Bytes (UInt32BE) | Big-endian 32-bit integer identifying the platform root key in the keyring. |
| Bytes 5–6 | Tenant Key Version | 2 Bytes (UInt16BE) | Big-endian 16-bit integer identifying the tenant key rotation version. |
| Bytes 7–18 | AES Initialization Vector (Nonce) | 12 Bytes | Cryptographically secure random 96-bit initialization vector generated per encryption operation. |
| Bytes 19–34 | AES-GCM Authentication Tag | 16 Bytes | 128-bit GCM authentication tag verifying ciphertext and AAD integrity. |
| Bytes 35+ | Encrypted Ciphertext Payload | Variable | AES-256-GCM encrypted field value payload. |
Key lifecycle & hard gating
Tenant key operations follow a strict, auditable lifecycle designed to prevent unencrypted leaks:
1. Mandatory key initialization gate
Administrators cannot declare `Confidential` or `Secret` custom fields until the tenant's cryptographic key has been initialized. The API validator enforces this rule server-side.2. Zero-downtime key rotation
Rotating a key creates version N+1 for new writes while version N remains enabled in the keyring. Historical records remain instantly readable.3. Non-blocking database rewrap
An asynchronous background worker (`TenantKeyRewrapJob`) scans records in cursor-paginated batches, decrypts using historical keys, and re-encrypts using active key version N+1.4. Cryptographic audit trail
Every key creation, rotation, revocation, and individual field value reveal event is immutably logged with actor identity, IP address, and timestamp.
Live database rewrap migration engine
Large-scale enterprise datasets require key migration without database outages or table locks:
| Operational Strategy | Engine Implementation |
|---|---|
| Zero table locks | Uses cursor-based pagination and optimistic concurrency (`RowVersion`) to update individual rows without exclusive table locks. |
| Configurable cursor batching | Processes 500 records per loop iteration, throttling execution to avoid I/O starvation on production database instances. |
| Crash-safe & idempotent | If the process restarts, the cursor resumes from the last completed offset. Already-migrated records are skipped safely. |
| Real-time metrics & progress | Reports processed count, failure count, throughput, and completion percentage to the Studio dashboard and admin portal. |
| Platform cluster rewrap | SuperAdmin-initiated migration that rewraps all tenant secrets under the rotated platform key and updates entity field values across all tenants with zero downtime. |
Management interfaces
Operators and developers have three complementary interfaces for managing encryption:
- Tenant Security Portal: Web UI at `/custom-fields/security` for self-service rotation and rewrap monitoring.
- SCRIPE CLI: Comprehensive terminal tooling via `scripe crypto status`, `rotate`, `rewrap`, `verify`, and `revoke`.
- SCRIPE Studio: Visual interactive dashboard at `/crypto` with keyring tables and live migration progress bars.