Security & Credential Management

Core Principles

Heicode is a SaaS product — it can't push credential management onto the user, and it can't let secrets end up scattered across Git, Markdown, logs, or a sub-Agent's long-lived state.

Security goals:

• Users authorize resources; the platform custodies credentials.
• The Heicode server-side database only stores metadata and secret_ref.
• Long-lived credentials go into the credential vault.
• Sub-Agents only ever get short-lived, least-privilege, auditable credentials.
• High-risk actions must be approved in the client.

Credential Categories

Credential Vault

User-facing name: credential vault.

Technical implementation: OpenBao (openbao:// references, service-identity auth).

Users never need to log into OpenBao directly, or see the OpenBao console.

The user-facing account security page exposes only account-level security controls (change password, manage access tokens, delete account) — never any raw credential material for connected resources:

Credential Write Flow

User connects a resource via the readiness checklist
-> Heicode receives the authorization result
-> Heicode's backend writes it to OpenBao
-> OpenBao returns or forms a secret_ref
-> Heicode's DB stores the secret_ref
-> The frontend only shows a redacted reference and status

Heicode's APIs must never return plaintext credentials — writes are validated to ensure secret_ref is in openbao:// format, and anything else is rejected outright. Logs, error messages, and audit summaries must never contain plaintext credentials either.

Credential Lifecycle

When an account is disabled or an organization is closed, related credentials are immediately marked revoked and stop being usable for new tasks; the corresponding Key Vault key material is soft-deleted first, then purged irrecoverably after the retention period (30 days by default). Credentials support rotation: after rotation, the secret_ref stays the same — only the underlying version is updated, so users don't need to redo the resource-connection flow.

Sub-Agent Credential Access

Sub-Agents never store long-lived credentials.

Recommended flow:

User confirms the recommendation summary
-> Heicode generates authorization and runtime policy in the background
-> Agent platform starts the sub-Agent
-> Agent platform binds the runtime identity
-> Sub-Agent requests to use a resource
-> High-risk actions first go through client-side approval
-> Once approved, a short-lived credential is issued
-> The short-lived credential is injected into the runtime
-> It expires at TTL or when the task ends

High-Risk Actions

High-risk actions include:

• Production deployment.
• Creating, deleting, or scaling cloud resources.
• Database migration or writes.
• Accessing production credentials.
• Large model-budget consumption.

Every approval must record:

• Approver.
• Approval time.
• Action type.
• Resource scope.
• Risk level.
• TTL.
• The corresponding deployment or task.

Prohibited

• Never write tokens into Git.
• Never write credentials into Markdown.
• Never let the frontend return plaintext credentials.
• Never print credentials in logs.
• Never inject long-lived cloud credentials into a sub-Agent.
• Never expose OpenBao as a public-facing endpoint.
• Never hand a CodeGW key's raw value to the client for long-term storage.

How to Explain This to Users

Recommended copy:

Heicode stores your authorized credentials in the credential vault. You just connect resources via the readiness checklist and confirm the recommended scope — the platform generates the necessary authorization and runtime parameters in the background. Credentials are never written to Git, docs, logs, or a sub-Agent's long-lived state.

Acceptance Criteria