SENSE-O Credential Store

The SENSE Orchestrator provides an encrypted credential store for secrets used by participating drivers and workflows.

How It Works

System administrators manage credentials through the portal or API. Internal workflows retrieve the credentials they need through the credential service. The master key is loaded at startup from a mounted secret file or an inline environment value, while the database holds values encrypted at rest alongside basic metadata.

flowchart TB
    accTitle: SENSE-O credential store architecture
    accDescr: A system administrator manages credentials through an admin-only API. A mounted key file supplies the in-memory master key to the credential service. The service encrypts values in the database and supplies a token to project synchronization for its configured upstream URL.
    admin["System Admin<br/>portal or API"]
    file["Mounted secret<br/>read-only key file"]
    subgraph orch["SENSE Orchestrator"]
        api["Credential API<br/>SYSTEM_ADMIN only, no-store"]
        svc["Credential service<br/>AES-256-GCM"]
        key["Master key<br/>held in memory"]
        sync["Project sync<br/>fixed credential reference"]
    end
    db[("rainsdb: sense_cred<br/>ciphertext + metadata<br/>no master key")]
    up["Upstream API (WFO)<br/>token checked against configured URL"]
    admin --> api --> svc
    file --> key --> svc
    svc <--> db
    svc --> sync --> up

Secret values are generally decrypted only for internal use, although owners can make an authorized read as needed. The reveal process returns plaintext to the browser or API caller, and should be treated with care.

Credential Schema

Each credential is one row in the sense_cred table, with the following fields:

Field	Purpose
Scope and name	Identifies the credential and the workflow that owns it
Value	The secret, stored as AES-256-GCM ciphertext with an authentication tag
Nonce and key version	Identifies the inputs needed to decrypt the value
Description	Notes such as “Upstream API token for ESE project sync”
Created and updated, by and at	Records the original creator and the most recent value update
Last used at	Records internal use, updated at most once per hour

The store does not persist the plaintext value or master key in the database. Credential reveal does not update the last-used timestamp.

Protection at Rest

A database copy or backup alone does not provide the master key needed to decrypt the stored values.

Encryption. Values are sealed with AES-256-GCM. Each write generates a fresh random 96-bit nonce.
Row binding. Each ciphertext is authenticated against its scope, name, and key version. Moving it to a different scope or name, or relabeling its key version, causes authentication to fail.
Master key isolation. The 256-bit key is supplied through SENSE_CRED_KEY or a file selected by SENSE_CRED_KEY_FILE. Configure exactly one source. Prefer a read-only mounted secret file and keep key material out of application images, deployable EAR files, and version control. The application retains the loaded key in memory.
Failure guards. A missing, malformed, ambiguous, or unreadable current key makes the store unavailable. The store rejects credential mutations, reveal, and re-encryption while unavailable. Status and metadata remain readable; unrelated Orchestrator operations do not require the credential store.
Diagnostics. At startup, SENSE-O checks stored rows using the loaded keys for their versions. It reports key mismatches, unavailable versions, and undecryptable rows. A current-key mismatch can make the store unavailable; individual row failures or missing previous keys do not necessarily disable the whole store.

Losing the matching key prevents recovery of an encrypted value from the database. Restore the matching key or replace the affected credential with a new value from its issuing system.

Access Control

Only SENSE System Admins (SYSTEM_ADMIN) can manage the store through its API. Internal consumers use the credential service through their own workflows.

Restricted Reveals. Only the original creator can reveal a credential, and such reveals are audited and logged. The current implementation also restricts replacement and deletion to the original creator.
Exposure Controls. Setting SENSE_CRED_REVEAL_DISABLED=true disables the reveal mechanism entirely, which prevents any external workflows or API calls from revealing credentials incidentally.
Credential Destination Check. Workflows should take care to associate their credentials with specific URLs and endpoints, and avoid sending the token if a target does not match the configured URL. Changing the URL through the settings workflow without supplying a replacement token can clear the stored token.

Auditing and Lifecycle

Audit Records

Each credential records its original creator, the most recent value update and actor, and its last internal use. SENSE-O logs credential set, delete, and re-encryption operations with the actor and relevant identifiers or counts.

Replacing or Removing a Secret

A credential’s owner with the System Admin role can replace its value in place or delete it directly. Revoking or reissuing an upstream token happens at the upstream issuing system, and operators can then update the stored value after obtaining its replacement.

Master Key Rotation

Keys carry positive integer version numbers. Previous keys can remain loaded for decryption while existing rows are re-encrypted under the current key.

Generate a new random 256-bit key with openssl rand -base64 32. Configure the current key as <new-version>:<base64-key>, using a version that has never been used for another key.
Retain the old key as <old-version>:<base64-key> in SENSE_CRED_KEY_PREVIOUS or a file selected by SENSE_CRED_KEY_PREVIOUS_FILE. Configure only one previous-key source and preserve any other keys still needed. Previous-key entries must include their versions and can be separated by commas or newlines. A bare current key without a version prefix is interpreted as version 1.
Restart or recreate the application as required by your deployment so it loads the new configuration. An environment-variable change in Docker Compose requires recreating the application container; restarting it alone retains its old environment.
In Admin Settings → Credentials, confirm Store Active, the expected Key Version, and the previous key marked LOADED. Resolve any key or verification warnings before continuing.
Select Re-encrypt under current key, then confirm Re-encrypt. Each eligible row is processed in its own transaction, and the operation can be repeated. Review the rewrapped, skipped, failed, and remaining counts.
Confirm that no rows remain on the old version and resolve any failures before removing the old key from the running application’s configuration. Restart or recreate the application to apply that change.

Operator Requirements

Generate master keys from a secure random source, never by hand.
Prefer read-only mounted key files. Configure the mount and SENSE_CRED_KEY_FILE explicitly for the deployment; setting the file variable alone does not create a mount.
Hold keys separately from database backups, so a single copied backup does not contain both.
After deployment, check Admin Settings → Credentials for Store Active, the expected key version, and any verification warnings. Key verification incomplete means the latest verification could not read the database; investigate database connectivity before rotating keys.