Secret Management

Documentation for Secret Management in the EigenLayer-AVS system.

Purpose and Scope#

This document describes the secret management functionality within the Ava SDK JS, which enables secure storage, retrieval, and management of sensitive information like API keys, tokens, and passwords. These secrets can be used in workflows without exposing sensitive values in workflow definitions. The secret management system provides scoping at user, workflow, and organization levels to control access to sensitive information.

For information about how to use these secrets within workflows, see Workflow System.

Sources:

Secret Data Model#

The secret management system uses a simple but flexible data model to represent and manage secrets.

Secret Class and Properties#

The Secret class implements the SecretProps interface, which defines the structure of a secret:

  • name: Unique identifier for the secret
  • secret: The sensitive value to be stored
  • workflowId: Optional ID of the workflow this secret belongs to
  • orgId: Optional ID of the organization this secret belongs to

When listing secrets, the ListSecretResponse interface is used, which notably excludes the actual secret value for security reasons.

Sources:

Secret Scoping System#

Secrets can be scoped to different levels, determining their visibility and accessibility.

  • User Level: Default scope. Secrets are accessible to all workflows created by the user.
  • Workflow Level: Secrets are accessible only to a specific workflow, identified by workflowId.
  • Organization Level: Secrets are accessible to all workflows within an organization, identified by orgId.

Sources:

Managing Secrets#

The SDK provides four main operations for managing secrets: create, list, update, and delete.

API Flow#

Sources:

Creating Secrets#

The createSecret method adds a new secret to the system with optional scoping:

The options parameter can include:

  • workflowId: Scope the secret to a specific workflow
  • orgId: Scope the secret to a specific organization
  • authKey: Use a specific auth key for the request

Usage examples:

Sources:

Listing Secrets#

The listSecrets method retrieves all available secrets for the authenticated user, optionally filtered by scope:

The response includes metadata about each secret (name and scope) but not the actual secret values for security reasons.

Usage example:

Sources:

Updating Secrets#

The updateSecret method modifies an existing secret's value:

Usage example:

Sources:

Deleting Secrets#

The deleteSecret method removes a secret from the system:

Usage example:

Sources:

Using Secrets in Workflows#

Secrets are automatically made available to nodes within workflows through the apContext.configVars object during execution.

Example of a custom code node that accesses a secret:

Sources:

Security Considerations#

The secret management system includes several security features:

  1. Isolation between users: Secrets are scoped to users based on authentication, preventing cross-user access.

  2. No value retrieval: The listSecrets method only returns metadata about secrets (name and scope), not the values themselves.

  3. Secure transmission: Secrets are transmitted securely via gRPC with authentication.

  4. Hierarchical access control: The scoping system (user, workflow, organization) provides granular control over secret access.

  5. Authentication requirement: All secret operations require a valid authentication key.

Sources:

Implementation Details#

The secret management functionality is implemented in the Client class, which extends BaseClient. The secret-related methods make gRPC calls to the AVS service, which handles the actual storage and retrieval of secrets.

The SDK provides a type-safe interface through TypeScript interfaces like SecretProps and SecretRequestOptions. The Secret class includes a toRequest method that converts a secret object to the gRPC request format.

Sources: