@aembit/edge-sdk

v1.34.1

Published

17 days ago

TypeScript SDK for the Aembit Edge API

0High
0Medium
0Low

quantifex

Aembit Edge TypeScript SDK

Official TypeScript / JavaScript SDK for interacting with the Aembit Edge API.

The Aembit Edge SDK enables workloads, serverless functions, AI agents, and MCP servers to authenticate and retrieve credentials dynamically without managing static secrets.

Features

🔐 Zero Hardcoded Secrets: Authenticate via workload identity (AWS IMDSv2, AWS STS Role, GCP Identity Token, GitHub Actions OIDC, Generic OIDC).
🔄 Automatic Token Lifecycle: Built-in in-memory bearer token caching and proactive background refresh.
⚡ Tree-Shakeable Subpath Imports: Optimize bundle sizes by importing only the trust providers you need.
🪵 Structured Logging: Pluggable AembitLogger interface compatible with Winston, Pino, or standard console.
📦 Modern ESM & TypeScript: Strict type safety targeting Node.js >=20.

Installation

npm install @aembit/edge-sdk

Quickstart

import { EdgeClient, trustProviders } from "@aembit/edge-sdk"

// 1. Initialize the client with your Aembit tenant and Trust Provider
const client = new EdgeClient({
  baseUrl: "https://tenant.aembit.io",
  clientId: "your-edge-sdk-client-id",
  trustProvider: trustProviders.awsMetadataService(),
})

// 2. Retrieve credentials for your target server
const credential = await client.getCredential({
  server: {
    host: "db.internal",
    port: 5432,
  },
})

console.log("Retrieved credential data:", credential.data)

Supported Trust Providers

| Trust Provider | Factory Method | Subpath Import | | :--- | :--- | :--- | | AWS IMDSv2 (EC2) | trustProviders.awsMetadataService() | @aembit/edge-sdk/trust-providers/aws-metadata-service | | AWS IAM Role (Lambda/ECS) | trustProviders.awsRole({ region: "us-east-1" }) | @aembit/edge-sdk/trust-providers/aws-role | | GCP Identity Token | trustProviders.gcpIdentityToken({ identityToken }) | @aembit/edge-sdk/trust-providers/gcp-identity-token | | GitHub Actions OIDC | trustProviders.githubIdentityToken({ identityToken }) | @aembit/edge-sdk/trust-providers/github-identity-token | | GitLab CI/CD OIDC | trustProviders.gitlabIdentityToken({ identityToken }) | @aembit/edge-sdk/trust-providers/gitlab-identity-token | | Kubernetes Service Account | trustProviders.k8sServiceAccount({ serviceAccountToken }) | @aembit/edge-sdk/trust-providers/k8s-service-account | | Terraform Cloud OIDC | trustProviders.terraformCloudIdentityToken({ identityToken }) | @aembit/edge-sdk/trust-providers/terraform-cloud-identity-token | | Generic OIDC Token | trustProviders.oidcIdToken({ identityToken }) | @aembit/edge-sdk/trust-providers/oidc-id-token |

Provider Usage Examples

AWS IAM Role (STS)

import { EdgeClient, trustProviders } from "@aembit/edge-sdk"

const client = new EdgeClient({
  baseUrl: "https://tenant.aembit.io",
  clientId: "your-edge-sdk-client-id",
  trustProvider: trustProviders.awsRole({ region: "us-east-1" }),
})

GitHub Actions / OIDC Identity Tokens

import { EdgeClient, trustProviders } from "@aembit/edge-sdk"

const client = new EdgeClient({
  baseUrl: "https://tenant.aembit.io",
  clientId: "your-edge-sdk-client-id",
  trustProvider: trustProviders.githubIdentityToken({
    identityToken: "YOUR_GITHUB_OIDC_TOKEN", // Or a dynamic resolver function: () => fetchOidcToken()
  }),
})

Google Cloud (GCP Identity Token)

import { EdgeClient, trustProviders } from "@aembit/edge-sdk"

const client = new EdgeClient({
  baseUrl: "https://tenant.aembit.io",
  clientId: "your-edge-sdk-client-id",
  trustProvider: trustProviders.gcpIdentityToken({
    identityToken: "YOUR_GCP_ID_TOKEN",
  }),
})

Customizing Provider IDs (Multi-Identity & Observability)

All Trust Provider options accept an optional id parameter. This identifier is attached to structured logs (trustProviderId) and returned in AuthSession metadata when calling client.authenticate().

By default, providers use standard identifiers (e.g., "gitlab-identity-token", "terraform-cloud-identity-token"). You can customize id when:

Running multiple client workloads or pipeline stages in the same application.
Correlating authentication events with internal APM, Datadog, or OpenTelemetry service registries.

const trustProvider = trustProviders.terraformCloudIdentityToken({
  id: "tfc-prod-workspace",
  identityToken: process.env.TFC_WORKLOAD_IDENTITY_TOKEN!,
})

Optimizing Bundle Size (Subpath Imports)

When bundling for serverless functions (AWS Lambda, Cloudflare Workers, Vercel) where bundle size is critical, import individual provider factories via subpaths:

import { EdgeClient } from "@aembit/edge-sdk"
import { createAwsRoleTrustProvider } from "@aembit/edge-sdk/trust-providers/aws-role"

const client = new EdgeClient({
  baseUrl: "https://tenant.aembit.io",
  clientId: "your-edge-sdk-client-id",
  trustProvider: createAwsRoleTrustProvider({ region: "us-east-1" }),
})

Logging & Observability

By default, the SDK remains completely silent and outputs nothing to the console. To capture internal operational events (token caching, request lifecycles, and errors), supply an optional logger implementing AembitLogger:

import { EdgeClient, trustProviders, type AembitLogger } from "@aembit/edge-sdk"

// Adapt any logger (e.g. Winston, Pino, or standard console)
const logger: AembitLogger = {
  debug: (message, context) => console.debug(`[DEBUG] ${message}`, context ?? ""),
  info: (message, context) => console.info(`[INFO] ${message}`, context ?? ""),
  warn: (message, context) => console.warn(`[WARN] ${message}`, context ?? ""),
  error: (message, context) => console.error(`[ERROR] ${message}`, context ?? ""),
}

const client = new EdgeClient({
  baseUrl: "https://tenant.aembit.io",
  clientId: "your-edge-sdk-client-id",
  trustProvider: trustProviders.awsMetadataService(),
  logger,
})

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme