PersistentAI API Documentation / @persistent-ai/fireflow-types / IVaultContextService

Interface: IVaultContextService

Defined in: packages/fireflow-types/src/execution/services/vault-context-service.ts:36

Vault context service for secret management during node execution.

Provides access to the FireFlow vault for storing, retrieving, and managing secrets. All secret values are re-encrypted via ECDH for transit - plaintext never reaches nodes.

Example

async execute(context: ExecutionContext): Promise<NodeExecutionResult> {
  const { vault, dbos } = context.services!;
  if (!vault) throw new Error('Vault service not available');

  const keyPair = await context.getECDHKeyPair();
  const publicKeyBase64 = Buffer.from(
    await subtle.exportKey('raw', keyPair.publicKey)
  ).toString('base64');

  const result = await dbos.runStep(
    () => vault.getSecretForExecution(secretId, ownerId, publicKeyBase64),
    { name: 'vault-get-secret' }
  );

  // result is directly compatible with wrapSecret()
  return {};
}

Properties

createSecret()

createSecret: (params) => Promise<string>

Defined in: packages/fireflow-types/src/execution/services/vault-context-service.ts:50

Create a new secret (for VaultCreateNode).

Parameters

params

name

string

ownerId

string

scope

"user" | "workspace"

scopeId

string

secretType

string

value

Record<string, string>

Returns

Promise<string>

---

deleteSecret()

deleteSecret: (secretId, ownerId) => Promise<void>

Defined in: packages/fireflow-types/src/execution/services/vault-context-service.ts:74

Delete a secret (for VaultDeleteNode).

Parameters

secretId

string

ownerId

string

Returns

Promise<void>

---

getSecretForExecution()

getSecretForExecution: (secretId, ownerId, ecdhPublicKeyBase64) => Promise<{ encrypted: string; hkdfNonce: string; publicKey: string; secretType: string; }>

Defined in: packages/fireflow-types/src/execution/services/vault-context-service.ts:41

Get a secret re-encrypted for execution transit (ECDH). Returns data directly compatible with wrapSecret().

Parameters

secretId

string

ownerId

string

ecdhPublicKeyBase64

string

Returns

Promise<{ encrypted: string; hkdfNonce: string; publicKey: string; secretType: string; }>

---

getSecretMetadata()

getSecretMetadata: (secretId, ownerId) => Promise<{ id: string; name: string; secretType: string; } | null>

Defined in: packages/fireflow-types/src/execution/services/vault-context-service.ts:79

Get secret metadata without value (for UI/status checks).

Parameters

secretId

string

ownerId

string

Returns

Promise<{ id: string; name: string; secretType: string; } | null>

---

listSecrets()

listSecrets: (ownerId, filter?) => Promise<object[]>

Defined in: packages/fireflow-types/src/execution/services/vault-context-service.ts:62

List secrets metadata for an owner (for VaultListNode).

Parameters

ownerId

string

filter?

secretType?

string

Returns

Promise<object[]>

---

resolveExternalSecret()?

optional resolveExternalSecret: (provider, secretRef, ecdhPublicKeyBase64) => Promise<{ encrypted: string; hkdfNonce: string; publicKey: string; secretType: string; }>

Defined in: packages/fireflow-types/src/execution/services/vault-context-service.ts:88

Resolve a secret from an external vault provider (Phase 2).

Parameters

provider

string

secretRef

string

ecdhPublicKeyBase64

string

Returns

Promise<{ encrypted: string; hkdfNonce: string; publicKey: string; secretType: string; }>

---

updateSecret()

updateSecret: (secretId, ownerId, value) => Promise<void>

Defined in: packages/fireflow-types/src/execution/services/vault-context-service.ts:69

Update a secret value (for VaultUpdateNode).

Parameters

secretId

string

ownerId

string

value

Record<string, string>

Returns

Promise<void>