@r4security/sdk

Official R4 SDK for Node.js. Provides zero-trust programmatic access to R4 vault secrets for agent runtimes.

Installation

npm install @r4security/sdk

Requires Node.js >= 18.0.0 (uses native fetch). The published SDK is self-contained and does not require any other R4 package at runtime.

Quick Start

import R4 from '@r4security/sdk'

const r4 = await R4.create({
  apiKey: 'agent_access_key.secret',
  privateKeyPath: './agent-private-key.pem',
})

const password = r4.env.PRODUCTION_DB_PASSWORD

API

R4.create(config): Promise<R4>

Static factory that creates and initializes an R4 instance. This is the recommended entry point.

r4.env: Record<string, string>

Access project environment variables as a flat key-value map. Keys are SCREAMING_SNAKE_CASE (VAULT_ITEM_NAME_FIELD_NAME).

r4.refresh(): Promise<void>

Re-fetches environment variables from the API. Useful for long-running processes that need fresh secrets.

Configuration

| Option | Required | Description | | ----------- | -------- | ------------------------------------------------- | | apiKey | Yes | AGENT-scoped API key in format {accessKey}.{secret} | | privateKey | No | PEM-encoded RSA private key kept locally by the agent | | privateKeyPath | No | Path to the PEM-encoded RSA private key | | projectId | No | Optional project ID filter for accessible vaults | | dev | No | Use https://dev.r4.dev when baseUrl is not set | | trustStorePath | No | Optional path for the signer trust-store JSON | | baseUrl | No | API base URL (defaults to https://r4.dev) |

You must provide either privateKey or privateKeyPath. When both dev and baseUrl are provided, baseUrl wins.

How It Works

1. Authenticates with an AGENT-scoped API key
2. Registers the runtime's public key through POST /api/v1/machine/vault/public-key
3. Becomes eligible for vault-backed access grants after that first registration
4. Lists accessible vaults through the machine API
5. Fetches each vault's wrapped DEK and signed org user-key directory plus transparency proof
6. Verifies the signed org directory, checks the append-only transparency proof, and continuity-pins the signer in the local trust store
7. Verifies wrapped-DEK signatures against that authenticated signer set
8. Unwraps the DEK locally with the agent private key
9. Verifies signed vault summary/detail checkpoints, then decrypts field ciphertext locally into a flat SCREAMING_SNAKE_CASE env map

Operationally, the runtime should complete that first public-key registration before operators assign security-group, project, or direct vault access to the agent. Re-registering the same key is safe, but rotating to a different key is currently blocked while vault-backed access still exists.

Trust Store

The SDK trust store persists:

• continuity pins for org-directory signer/user keys
• append-only transparency head pins for each org directory
• rollback pins for signed metadata versions

In production r4.dev environments, the first trusted org-directory head is now anchored to the public witness at https://transparency.r4.dev and verified with the embedded witness root before the SDK accepts the API's first signer set. Later directory updates must still present a valid append-only proof from the pinned head, later signer rotations must present continuity signatures, and every vault-specific signer subset must match the signed org directory returned by the machine API.

The remaining gap is that the public witness still lives in the same AWS account, so this is stronger than API-only TOFU but not yet a fully independent external auditor or gossip network. Development hosts such as https://dev.r4.dev skip the public witness anchor and fall back to local trust pins so non-production environments do not depend on the public witness bucket. By default the SDK stores this beside the private key as <privateKeyPath>.trust.json, or in ./.r4-trust-store.json when the private key is passed inline.

Development

pnpm run test     # Run mocked zero-trust SDK tests from test/
pnpm run test:pack # Verify npm publish excludes src/ and test/
pnpm run build    # Build with tsup
pnpm run clean    # Remove lib/

The published SDK is controlled by the files allowlist in package.json, so only lib/ is shipped. Package-local tests live in test/ and are validated with npm pack --dry-run through pnpm run test:pack.