npm package: @r4security/sdk
Description: Official R4 SDK for Node.js — programmatic access to R4 vault secrets
Latest version: 0.0.5

# @r4security/sdk

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

## Installation

```bash
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

```typescript
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

```bash
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`.