@elevasis/sdk 0.5.12 → 0.5.14

package/reference/security/credentials.mdx

@@ -1,141 +0,0 @@
----
-title: "Credential Security"
-description: "Three-layer credential model: platform tools (server-side injection), http tool (arbitrary APIs), getCredential() (explicit opt-in raw access) -- .env scope and security boundaries"
-loadWhen: "Setting up integrations or configuring tool access"
----
-
-This reference covers the Elevasis credential security model. Read it when helping a user connect to an external service, set up platform tools, or understand why environment variables are not used in workflows.
-
----
-
-## The Core Rule
-
-Integration credentials are never stored in `.env` and never available via `process.env` inside worker threads.
-
-Credentials live in the platform credential system, created via the command center UI. Worker threads access credentials only through controlled channels: `platform.call()` (server-side injection) or `platform.getCredential()` (explicit opt-in).
-
-`.env` contains only `ELEVASIS_API_KEY`, used by the CLI for authentication. It is never uploaded to the platform and never injected into workers.
-
----
-
-## Three-Layer Model
-
-### Layer 1: Platform Tools (Default)
-
-All platform tools resolve credentials server-side. The tool dispatcher in the API process looks up the credential by name, injects it into the service call, and returns only the result. Credential values never cross the postMessage boundary into the worker.
-
-```typescript
-// Credential 'my-gmail' is resolved server-side -- value never enters worker memory
-const result = await platform.call({
-  tool: 'gmail',
-  method: 'sendEmail',
-  credential: 'my-gmail',
-  params: { to: '...', subject: '...', body: '...' },
-})
-```
-
-This is the default pattern for all integrations that have a platform adapter (Gmail, Attio, Stripe, Resend, etc.).
-
-### Layer 2: HTTP Platform Tool
-
-For APIs without a dedicated platform adapter, use the `http` platform tool. Credentials are resolved and injected server-side before the outgoing HTTP request.
-
-```typescript
-const result = await platform.call({
-  tool: 'http',
-  method: 'request',
-  credential: 'my-custom-api',
-  params: {
-    url: 'https://api.example.com/v1/data',
-    method: 'GET',
-    headers: { 'Content-Type': 'application/json' },
-  },
-})
-// result = { status: 200, headers: {...}, body: {...} }
-```
-
-**Supported credential injection patterns:**
-
-| Pattern | Credential Config | How Injected |
-| --- | --- | --- |
-| Bearer token | `{ type: 'bearer', token: 'sk_...' }` | `Authorization: Bearer sk_...` header |
-| API key header | `{ type: 'api-key-header', header: 'X-API-Key', key: 'ak_...' }` | Custom header with key value |
-| Basic auth | `{ type: 'basic', username: '...', password: '...' }` | `Authorization: Basic base64(user:pass)` header |
-| Query parameter | `{ type: 'query-param', param: 'api_key', value: 'ak_...' }` | Appended to URL query string |
-| Body field | `{ type: 'body-field', field: 'apiKey', value: 'ak_...' }` | Merged into JSON request body |
-| Custom header | `{ type: 'custom-header', header: 'X-Custom', value: '...' }` | Arbitrary header with value |
-
-The credential type is selected when creating the credential in the command center UI.
-
-### Layer 3: getCredential() (Explicit Opt-In)
-
-For cases where a third-party SDK must be initialized with a raw key (e.g., `new Stripe(key)`), use `platform.getCredential()`. This is an explicit opt-in that causes the credential value to enter worker memory.
-
-```typescript
-import { platform } from '@elevasis/sdk/worker'
-
-// Explicit opt-in -- secret enters worker memory for duration of execution
-const cred = await platform.getCredential('my-stripe-key')
-const stripe = new Stripe(cred.credentials.secretKey)
-```
-
-`getCredential()` returns `{ provider: string, credentials: Record<string, string> }`. The fields in `credentials` depend on the credential type stored in the command center.
-
-**Security guardrails:**
-
-- All `getCredential()` calls are logged with credential name, deployment ID, and execution ID
-- Workers are ephemeral (destroyed after each execution) -- no credential persistence
-- Use `platform.call()` with the `http` tool instead when possible
-
----
-
-## Credential Setup
-
-Credentials are created in the command center UI:
-
-1. Open the Elevasis command center
-2. Navigate to Credentials
-3. Click "Add Credential"
-4. Enter a name (e.g., `my-gmail`, `production-attio`, `custom-api`)
-5. Select the credential type (bearer, api-key-header, basic, etc.)
-6. Enter the secret values
-7. Save
-
-The credential name is what you pass as `credential: 'my-gmail'` in `platform.call()`.
-
-Credential names are case-sensitive. A mismatch causes a `PlatformToolError` with the message "credential not found."
-
----
-
-## .env Scope
-
-`.env` in your workspace contains only:
-
-```
-ELEVASIS_API_KEY=sk_your_key_here
-```
-
-This key authenticates CLI operations (`elevasis-sdk deploy`, `elevasis-sdk check`, `elevasis-sdk exec`). It is never uploaded to the platform and never injected into workers.
-
-Do not put integration API keys in `.env`. They will not be available inside workflows.
-
----
-
-## Choosing a Credential Pattern
-
-| Situation | Pattern |
-| --- | --- |
-| Using a supported platform tool (Gmail, Attio, Stripe, etc.) | `platform.call()` with the tool name |
-| Calling an API not in the tool catalog | `platform.call()` with `tool: 'http'` |
-| Third-party SDK that requires a raw key | `platform.getCredential()` |
-| CLI authentication | `ELEVASIS_API_KEY` in `.env` only |
-
----
-
-## Migrating from elevasis-sdk env
-
-If you previously set integration credentials via `elevasis-sdk env set`, that command no longer exists. Use `elevasis-sdk env list` to see what was set, then recreate each entry as a platform credential in the command center. Update workflow code from `process.env.KEY` to `platform.call({ tool: 'http', credential: '...', ... })` or `platform.getCredential('...')`, then redeploy. The `.env` file remains but is scoped to `ELEVASIS_API_KEY` only.
-
----
-
-**Last Updated:** 2026-02-26