Introduction

DeepSeek Harness (DSH) uses a plugin-based architecture, and credential management is a critical part of it. Traditional local file storage (dsh-credentials-local) is suitable for single-node execution, but it has limitations when credentials need to be shared across multiple instances. The dsh-credentials-mysql plugin is designed to address this issue. It migrates credential storage from local files to a MySQL database, supports multi-process sharing and transactional consistency, and is the standard credential component for building distributed DSH deployments.

Plugin Overview

This is a MySQL-backed credential provider plugin under the admin-security category. It is maintained by sandersyao and released under the MIT license. The plugin implements DSH’s CredentialProvider interface, providing credential read, set, and clear capabilities consistent with local file storage behavior, while adding database persistence, shared access, and field-level encryption.

Core Features

  1. MySQL persistent storage: Persists credential data to a database and supports concurrent access from multiple processes.
  2. AES-256-GCM field-level encryption: Supports encrypted storage of sensitive fields (such as credential values and payloads). The key is derived using SHA-256 and is not stored in the database.
  3. Shared database deployment: Can be used together with plugins such as dsh-workspace-bootstrap and dsh-storage-mysql, using the same MySQL instance as a shared backend.
  4. Transactional consistency: Uses InnoDB transactions and row locks (SELECT ... FOR UPDATE) to ensure safety during concurrent writes, with support for deadlock retries.
  5. Connection pool configuration: Includes a built-in connection pool mechanism with a default size of 10, which is configurable.

Installation and Enablement

Install the dependency via npm, then register the plugin in your initialization code.

import { MysqlCredentialProvider } from '@sandersyao/dsh-credentials-mysql'

await ctx.plugin(MysqlCredentialProvider, {
  connection: { tablePrefix: process.env.CREDENTIALS_TABLE_PREFIX },
})

After registration, ctx.credentials will be handled by the MySQL provider.

Configuration

The credential store’s connection information and encryption settings are injected via environment variables. The plugin prioritizes variables prefixed with CREDENTIALS_*, and falls back to MYSQL_* variables if they are not set.

Required configuration:
- CREDENTIALS_HOST: MySQL host (default 127.0.0.1).
- CREDENTIALS_PORT: MySQL port (default 3306).
- CREDENTIALS_USER: database username.
- CREDENTIALS_PASSWORD: database password.
- CREDENTIALS_DATABASE: target database name.
- CREDENTIALS_TABLE_PREFIX: table prefix, used to distinguish tables created by different plugins. It must match the regex ^[A-Za-z0-9_]+$.

Optional configuration:
- CREDENTIALS_ENCRYPTION_KEY: encryption key. If set to an empty string, values are stored in plaintext (a warning will be shown at startup). A 32-byte hexadecimal string or any other string is acceptable.
- CREDENTIALS_POOL_SIZE: connection pool size (default 10).
- CREDENTIALS_SCHEMA_AUTO_MIGRATE: whether to automatically migrate the table schema at startup (default true).
- CREDENTIALS_SSL_REQUIRED: mandatory TLS requirement (currently reserved).

Storage Structure and Concurrency

The plugin creates three tables in the database, all using CREDENTIALS_TABLE_PREFIX as the prefix:
- ${prefix}credential_refs: stores references (ref_name and value).
- ${prefix}credential_records: stores records (rec_key, kind, payload).
- ${prefix}credential_meta: stores schema version information.

Concurrency handling:
modifyRecord operations are mutually exclusive in multi-process environments. Row-level locking and transaction isolation are implemented using SELECT ... FOR UPDATE, ensuring data safety when tokens are refreshed concurrently. Write operations are atomic, and InnoDB guarantees that committed data will not be lost.

Notes

  1. No hot reload: The plugin does not listen for file changes, so data modified directly in MySQL is not reflected in real time in running processes (you must wait for the next re-resolution).
  2. No automatic migration: It does not support automatically migrating data from the local .credentials.yaml file to MySQL.
  3. TLS reserved: CREDENTIALS_SSL_REQUIRED is currently a reserved feature and is not yet enabled.
  4. Dependency versions: The plugin uses peerDependencies at version ^0.1.5-rc.1 from the DSH ecosystem. Compatibility should be verified before installation.

Summary

dsh-credentials-mysql provides a standardized MySQL credential storage solution, suitable for DeepSeek Harness deployments that require multi-node collaboration. By configuring connection pool and encryption parameters, you can achieve good read and write performance while maintaining security. For more details, see the plugin directory or the source repository.