@r4security/sdk 0.0.2

package/README.md

@@ -0,0 +1,95 @@
+# @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. Lists accessible vaults through the machine API
+4. Fetches each vault's wrapped DEK and signed org user-key directory plus transparency proof
+5. Verifies the signed org directory, checks the append-only transparency proof, and continuity-pins the signer in the local trust store
+6. Verifies wrapped-DEK signatures against that authenticated signer set
+7. Unwraps the DEK locally with the agent private key
+8. Verifies signed vault summary/detail checkpoints, then decrypts field ciphertext locally into a flat `SCREAMING_SNAKE_CASE` env map
+
+## 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.
+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
+pnpm run build    # Build with tsup
+pnpm run clean    # Remove lib/
+```