Secret Types

QNSI Vault Service (port 8090) stores an opaque secret payload plus metadata. The platform does not enforce a typed secret schema (for example: "database", "certificate", etc.).

Service Configuration

From apps/vault-service/src/config/env.ts:

Setting	Environment Variable	Default
Port	PORT	8090
Default lease TTL	LEASE_DEFAULT_TTL_SECONDS	3600 (1 hour)
Max lease TTL	LEASE_MAX_TTL_SECONDS	86400 (24 hours)
PQC algorithm	PQC_ALGORITHM	kyber-768
Master key ID	KEY_ID	vault-master-key

Rotation Worker

Setting	Environment Variable	Default
Enabled	ROTATION_WORKER_ENABLED	true
Poll interval	ROTATION_WORKER_POLL_INTERVAL_MS	60,000 (1 min)
Batch size	ROTATION_WORKER_BATCH_SIZE	10

Secret payload

Create a secret

POST /vault/v1/secrets
Authorization: Bearer <token>
Content-Type: application/json

{
	"tenantId": "<tenant_uuid>",
	"name": "example-secret",
	"payload": "<base64_payload>",
	"metadata": {},
	"rotationPolicy": {
		"intervalSeconds": 86400,
		"expiresAt": 1700000000
	}
}

Notes:

• payload is a base64-encoded string.
• metadata is a JSON object and is stored alongside the secret.
• rotationPolicy supports intervalSeconds and optional expiresAt (unix seconds).

The name and metadata fields can describe an application-level category, but they do not change how the service encrypts or validates the payload. Examples such as database passwords, webhook credentials, API tokens, certificate material and TOTP seeds remain application conventions.

Do not place a plaintext credential in metadata. Metadata is for routing, ownership, classification and rotation information that is safe for authorized operators to inspect without retrieving the secret payload.

HSM/PKCS#11 Integration

Configure via KMS_PKCS11_CONFIGS_JSON:

[
  {
    "modulePath": "/usr/lib/softhsm/libsofthsm2.so",
    "slot": 0,
    "pin": "1234",
    "algorithm": "AES-KW",
    "profile": "strict"
  }
]

Production mode enforces:

• profile: "strict"
• allowPlainImport: false
• allowExtractUnwrapped: false

The example uses a placeholder PIN only. A production PIN must come from the deployment secret manager and must never be committed to the configuration document. A configured PKCS#11 module does not prove that a specific secret was wrapped by a qualified device; retain the live key/provider record and qualification evidence for that deployment.

Secret Metadata

All secrets include:

• id: Unique identifier
• version: Current version number
• createdAt: Creation timestamp
• updatedAt: Last update timestamp

Application-level classification

Use consistent metadata so owners can find and rotate secrets without inventing a server-side type:

{
  "application": "payments-api",
  "environment": "production",
  "classification": "credential",
  "owner": "platform-security",
  "rotationRunbook": "runbook-credential-rotation"
}

Metadata values should identify a controlled owner or runbook, not contain a personal email address or an unreviewed free-form secret.

Rotation semantics

A rotation policy schedules work; it does not guarantee the downstream system accepted the replacement credential. A controlled rotation should:

1. create or receive the replacement value through an approved path;
2. update the dependent system;
3. verify the new value works;
4. revoke the previous value;
5. record both QNSI and downstream timestamps;
6. preserve rollback instructions until the verification window closes.

Monitor the rotation worker and reconcile failed or overdue records. See Secret Rotation for worker configuration and operational status.

Access and verification

Grant payload read, write, rotation and deletion separately. Test both allowed and denied operations with a synthetic secret, and confirm audit records do not contain the plaintext or base64 payload. See Secrets Access Control and Audit Log Formats.