The Vault & Credentials

The Vault is ClientCove's encrypted credential store, attached to every asset and every location. When the vendor portal admin URL needs sharing among technicians, when the WiFi password belongs to one specific location, when an API key needs to live somewhere safer than a shared spreadsheet — the vault is where it goes.

What the Vault Is

Each asset and each location can store an unlimited number of credential sets — labeled collections of usernames, passwords, API keys, and notes. The data is:

• Encrypted at rest with AES-256-CBC using your WordPress secret keys
• Decrypted only on demand, after the requesting user verifies a one-time PIN
• Locked again after the user closes the page or manually re-locks
• Logged on every access — every PIN request, verification, and credential view is recorded

The vault is intentionally NOT a general-purpose password manager (1Password, Bitwarden are better for that). It's an operational store — credentials tied to a specific asset/location that your team needs occasional access to.

How Encryption Works

Under the hood, the vault uses standard cryptography:

Component	Implementation
Algorithm	AES-256-CBC
Key	Derived from wp_salt('auth') — your WordPress AUTH_KEY salt
IV	Random 16-byte initialization vector per encryption
Storage format	Base64(IV + :: + ciphertext) in _vault_credentials post meta
Decryption	Server-side only, on PIN-verified AJAX request

Important properties:

1. Credentials never live in the database in plaintext — even with database access, an attacker can't read the vault without your WP salts.
2. Salts must stay secure — if wp-config.php (which contains the salts) is compromised, the vault is compromised.
3. Rotate salts carefully — changing AUTH_KEY invalidates all existing vault entries. Don't rotate without a re-encryption migration plan.

The encryption is symmetric — there's no public/private key system. The point is server-side protection, not end-to-end encryption to the client browser (the browser sees plaintext after PIN verification, by design — the user needs the credentials).

Where Vaults Live

Vaults are attached to:

Type	Where	Access
Asset Vault	Single-asset workspace, Vault tab	Anyone with view access to the asset, after PIN verification
Location Vault	Single-location workspace, Vault tab	Anyone with view access to the location, after PIN verification

Both vaults use the same encryption and PIN flow — the underlying functions are shared (shared-vault-encryption.php).

PIN-Gated Access

Even users who can view the asset/location must verify a fresh PIN before the vault unlocks. This adds a second factor for sensitive credentials.

Why PIN gate?

• Stops casual browsing — opening an asset page doesn't reveal credentials
• Adds an audit trail event for every access (the PIN request itself is logged)
• Validates the user has access to their email account at access time
• Limits the impact of a stolen session — the attacker still needs the email account

PIN properties

• 6 digits (000000 to 999999)
• Random — cryptographically generated via mt_rand
• 15-minute expiry
• Single-use — verifying consumes the PIN; new access needs a new PIN
• Per-user, per-asset — your PIN for asset A is different from your colleague's PIN for asset B

PINs are stored as a WordPress transient (vault_pin_<asset_id>_<user_id>) so they auto-expire and survive server restarts.

Requesting a PIN

The first time you open the Vault tab on an asset (or after the previous session expired):

1. The Vault tab shows a yellow "Protected Content" alert
2. Click Request Access PIN
3. ClientCove generates a random 6-digit PIN
4. The PIN is stored as a 15-minute transient
5. An email is sent to your WordPress account email with the PIN
6. The Vault tab swaps to a PIN entry form

The email includes:

• The 6-digit PIN
• The asset/location name
• Expiry time
• A reminder that all access is logged

If you didn't receive the email:

• Check spam/junk
• Click Resend on the PIN form to send a new code (invalidates the old one)
• Verify the portal's email configuration (WP Mail SMTP, sender address, deliverability)

Verifying & Unlocking

Once you have the PIN:

1. Enter the 6-digit code in the PIN form
2. Click Verify PIN
3. ClientCove checks: PIN matches stored value AND not expired
4. On success, the vault unlocks
5. The PIN transient is deleted (single-use)
6. The audit log records the successful unlock with timestamp + IP

On failure (wrong PIN or expired):

• An error message appears
• You can re-enter or click Resend for a new PIN

Credential Sets

A vault can hold many credential sets — each one a labeled bundle of fields. Common patterns:

Use Case	Set Label
Vendor admin login	"Cloudflare Admin"
Recovery codes	"GitHub Recovery Codes"
API key	"Datadog API Key"
Network device	"Switch — Console Access"
Database access	"Production DB — Read Replica"

Each set has these fields (any can be empty):

• Label — human-readable name (e.g. "Vendor Portal — Production")
• Username / Login — email or username
• Password — the secret (rendered as password input, with show/hide toggle)
• API Key — for tokens too long for the password field, with multi-line textarea
• Notes — free-form text (recovery codes, MFA backup info, special instructions)

A vault with no sets shows "No credentials stored" inside the unlocked view.

Adding & Editing Credentials

To add credentials, you must be in edit mode for the asset (admin/editor only):

1. Open the asset workspace
2. Click Edit Asset (or append ?cove=run)
3. Scroll to the Vault section
4. Click Add Credential Set
5. Fill in the fields
6. Click Add Credential Set again to add another, or save the asset

Edit fields:

• Label — required
• Username / Login
• Password — typing into this field, the value is encrypted on save
• API Key — multi-line textarea
• Notes — multi-line, supports paragraph breaks

Click Save Changes at the bottom of the edit page. The credentials are encrypted and stored in _vault_credentials post meta.

Editing existing credentials

Same flow — open in edit mode, modify any field, save. The audit log records the change with field name and timestamp (but not the actual values, for security).

Removing a credential set

In edit mode, each set has an X button. Click to remove and save.

Read-only access

Outside edit mode (regular view + PIN unlocked), the vault is read-only. Users can:

• See all field values
• Toggle password visibility (show/hide)
• Copy values to clipboard

But they cannot add, change, or remove credentials without admin/editor edit access.

Locking the Vault

After unlock, the vault shows a green "Vault Unlocked" banner with a Lock button.

The vault locks automatically when:

• You navigate away from the asset/location
• You close the browser tab
• You refresh the page (PIN session is per-page-load)

Manual lock:

1. Click the Lock button in the green banner
2. The vault collapses back to the PIN-prompt state
3. Subsequent access requires a fresh PIN

Locking is best-practice for shared workstations or any time you're stepping away from the screen.

Vault Access Logging

Every vault interaction is recorded in the asset (or location) activity log:

Event	What's logged
PIN requested	User ID, timestamp, IP — credentials NOT decrypted yet
PIN verified	User ID, timestamp, IP — vault successfully unlocked
PIN failed	User ID, timestamp, IP, attempt count
Credentials viewed	User ID, timestamp (after unlock)
Credentials updated	User ID, timestamp, fields changed (NOT old/new values for security)
Vault locked	User ID, timestamp
Credential set added	User ID, timestamp, label of the new set
Credential set removed	User ID, timestamp, label of the removed set

The log is visible to admin/editor on the asset's Activity Log card. See Audit Log & Permissions for the full audit infrastructure.

Security Considerations

The vault is designed for operational credential storage with reasonable security. Some honest caveats:

Strong points

• Credentials never live in plaintext at rest
• PIN gate adds a second factor at access time
• Every access is logged for audit
• Email-based PIN delivery validates the user's email account
• Fresh PIN required per session — stolen sessions don't grant ongoing access

Limitations

• No end-to-end encryption — the server decrypts on demand, so server compromise = vault compromise
• PIN delivered via email — only as secure as the user's email account
• WordPress salt rotation breaks vaults — plan migrations carefully
• Browser sees plaintext after unlock — physical access to an unlocked browser session = visible credentials
• Not a 1Password replacement — for personal credential management, use a dedicated password manager

Best practices

1. Limit who has access to assets containing sensitive credentials
2. Use strong WordPress salts in wp-config.php and keep that file secure
3. Lock the vault when stepping away from your screen
4. Don't store master credentials here — use it for service accounts, not super-admin logins
5. Rotate stored passwords independently of vault — the vault doesn't enforce rotation
6. Review the audit log periodically for unexpected access patterns
7. Consider 2FA on the WordPress account itself — protects the email-PIN delivery channel