# REP — Runtime Environment Protocol: Complete Documentation

The full rep-protocol.dev documentation set, concatenated. Generated at build time.
Individual pages are available as Markdown at https://rep-protocol.dev/<path>.md — see https://rep-protocol.dev/llms.txt for the index.

---

# Quick Start — Runtime Environment Variables in 5 Minutes

> Get runtime environment variables in your frontend app in under 5 minutes. Install the SDK, rename your env vars, and run the gateway. No manifest required.

Source: https://rep-protocol.dev/quick-start/

The `.rep.yaml` manifest is entirely optional. The gateway works with just environment variables — the naming convention **is** the configuration.

1. **Rename your environment variables**

   Add the `REP_PUBLIC_`, `REP_SENSITIVE_`, or `REP_SERVER_` prefix to classify each variable:

   ```bash
   # Before (Vite)            → After (REP)
   VITE_API_URL               → REP_PUBLIC_API_URL
   VITE_FEATURE_FLAGS         → REP_PUBLIC_FEATURE_FLAGS

   # Before (CRA)             → After (REP)
   REACT_APP_API_URL          → REP_PUBLIC_API_URL

   # Should be encrypted in the browser
   REACT_APP_ANALYTICS_KEY    → REP_SENSITIVE_ANALYTICS_KEY

   # Should never reach the browser
   DB_PASSWORD                → REP_SERVER_DB_PASSWORD
   ```

2. **Install the SDK and update your code**

   ```bash
   npm install @rep-protocol/sdk
   ```

   Replace your `import.meta.env.*` / `process.env.*` reads:

   ```typescript
   import { rep } from '@rep-protocol/sdk';

   // Was: import.meta.env.VITE_API_URL
   const apiUrl = rep.get('API_URL');

   // With a default value for local development
   const apiUrl = rep.get('API_URL', 'http://localhost:3001');

   // Sensitive variable — encrypted, decrypted on demand
   const key = await rep.getSecure('ANALYTICS_KEY');
   ```

   `rep.get()` is **synchronous** — the SDK reads the payload from the DOM on import, before your first component renders. No loading state needed.

3. **Build your app (nothing changes)**

   ```bash
   npm run build
   ```

   The output is now environment-agnostic. The same `dist/` folder goes to every environment.

4. **Run the gateway**

     **Binary**

     ```bash
     REP_PUBLIC_API_URL=https://api.example.com \
     REP_PUBLIC_FEATURE_FLAGS=dark-mode,new-checkout \
     REP_SENSITIVE_ANALYTICS_KEY=ak_live_abc123 \
     ./rep-gateway --mode embedded --static-dir ./dist
     ```

     **Docker**

     ```bash
     docker run --rm -p 8080:8080 \
       -e REP_PUBLIC_API_URL=https://api.example.com \
       -e REP_PUBLIC_FEATURE_FLAGS=dark-mode,new-checkout \
       -e REP_SENSITIVE_ANALYTICS_KEY=ak_live_abc123 \
       -v "$(pwd)/dist:/static:ro" \
       ghcr.io/ruachtech/rep/gateway:latest \
       --mode embedded --static-dir /static
     ```

   Open `http://localhost:8080` — the gateway injected your variables into every HTML response.

## Changing config without rebuilding

Stop the gateway. Restart with different values. Same `dist/` folder, different runtime config:

```bash
REP_PUBLIC_API_URL=https://api.prod.example.com \
REP_PUBLIC_FEATURE_FLAGS=dark-mode \
REP_SENSITIVE_ANALYTICS_KEY=ak_live_prod_xyz \
./rep-gateway --mode embedded --static-dir ./dist
```

No rebuild. No new container image. This is the core proposition.

## Proxy mode

If you already have nginx, Caddy, or another static file server, run the gateway in front of it instead:

```bash
REP_PUBLIC_API_URL=https://api.example.com \
./rep-gateway --mode proxy --upstream localhost:80
```

The gateway intercepts `text/html` responses, injects the `<script>` tag, and passes everything else through unmodified.

## Dev mode — file watch hot reload

For local development, point the gateway at a `.env.local` file and let it watch for changes automatically — no signals, no restarts:

```bash
# .env.local
REP_PUBLIC_API_URL=http://localhost:3001
REP_PUBLIC_FEATURE_FLAGS=dark-mode
REP_SENSITIVE_ANALYTICS_KEY=ak_dev_abc123
```

```bash
./rep-gateway --mode embedded --static-dir ./dist \
  --hot-reload \
  --hot-reload-mode=file_watch \
  --env-file=.env.local \
  --watch-path=.env.local
```

Edit `.env.local` and save — the gateway picks up the changes immediately, re-encrypts sensitive vars with a fresh ephemeral key, and pushes a reload event over `/rep/changes` (SSE). Components using `rep.onChange()` re-render automatically without a browser refresh.

> **Tip**
>
> The CLI dev command handles this automatically: `npx @rep-protocol/cli dev --proxy http://localhost:5173` starts the gateway with file watch mode already enabled. See the [Local Development guide](/guides/development/).

## No build step? No framework?

REP works the same way with a single `index.html` and no bundler — see the [Simple HTML example](/examples/simple-html/) for the SDK loaded straight from a CDN.

## Build-tool plugins for local dev

Running `vite dev` or `next dev` without the gateway? Install the [Vite](/reference/plugins/vite/) or [Next.js](/reference/plugins/next/) plugin to get the same injected payload during development — no second terminal, no gateway binary needed locally.

## What's next?

- [Add a manifest file](/guides/manifest/) for startup validation and TypeScript type generation
- [Framework-specific guides](/frameworks/react/) for React, Vue, and Svelte adapters
- [Deploy with Docker](/deployment/docker-embedded/) for production containers
- [Variable classification](/concepts/variable-classification/) to understand the three-tier security model


---

# Installation — SDK, CLI, and Gateway Binary

> Install @rep-protocol/sdk, framework adapters for React/Vue/Svelte, the CLI tool, and the Go gateway binary. npm packages and Docker image options.

Source: https://rep-protocol.dev/guides/installation/

## SDK

The SDK is the only package required for your application code. Zero runtime dependencies, ~1.5KB gzipped.

```bash
npm install @rep-protocol/sdk
```

## Framework adapters (optional)

If you're using React, Vue, or Svelte, install the corresponding adapter for hot-reload-aware hooks and stores:

  **React**

  ```bash
  npm install @rep-protocol/react @rep-protocol/sdk
  ```

  **Vue**

  ```bash
  npm install @rep-protocol/vue @rep-protocol/sdk
  ```

  **Svelte**

  ```bash
  npm install @rep-protocol/svelte @rep-protocol/sdk
  ```

## Build-tool plugins (optional)

For the best dev experience, install the plugin for your build tool. These inject the REP payload during development so the SDK works without running the Go gateway:

  **Vite**

  ```bash
  npm install -D @rep-protocol/vite
  ```

  ```ts
  // vite.config.ts
  import { defineConfig } from 'vite';
  import { repPlugin } from '@rep-protocol/vite';

  export default defineConfig({
    plugins: [repPlugin()],
  });
  ```

  That's it — `rep.get()` and `rep.getSecure()` now work in `vite dev`. No gateway needed. See the [Vite plugin reference](/reference/plugins/vite/) for all options.

  **Next.js**

  ```bash
  npm install -D @rep-protocol/next
  ```

  ```tsx
  // app/layout.tsx
  import type { ReactNode } from 'react';
  import { RepScript } from '@rep-protocol/next';

  export default function RootLayout({ children }: { children: ReactNode }) {
    return (
      <html>
        <head><RepScript /></head>
        <body>{children}</body>
      </html>
    );
  }
  ```

  ```ts
  // app/api/rep/session-key/route.ts (only needed for SENSITIVE vars)
  export { GET } from '@rep-protocol/next/session-key';
  ```

  `RepScript` renders the REP payload during `next dev` and returns `null` in production — the gateway handles injection in prod. See the [Next.js plugin reference](/reference/plugins/next/) for all options.

> **Note**
>
> Build-tool plugins are for **development only**. In production, the Go gateway injects the payload. The plugins produce byte-identical output to the gateway, so the SDK works identically in both environments.

## CLI

The CLI provides `rep validate`, `rep typegen`, `rep lint`, and `rep dev` commands. It automatically downloads the correct gateway binary for your platform during installation.

```bash
npm install -g @rep-protocol/cli
```

Or use without installing:

```bash
npx @rep-protocol/cli validate
npx @rep-protocol/cli dev --proxy http://localhost:5173
```

## Gateway binary

The gateway is a standalone Go binary (~7MB). There are several ways to get it:

### Via the CLI (recommended)

The `@rep-protocol/cli` package downloads the gateway binary automatically during `npm install`.

### Docker image

```bash
docker pull ghcr.io/ruachtech/rep/gateway:latest
```

Or use in a multi-stage build:

```dockerfile
COPY --from=ghcr.io/ruachtech/rep/gateway:latest /usr/local/bin/rep-gateway /usr/local/bin/rep-gateway
```

### Direct download

Download from [GitHub Releases](https://github.com/ruachtech/rep/releases) for your platform:

Archives are published on the version tag — `v0.1.7`, not `gateway/v0.1.7`:

```bash
# Linux amd64
curl -fsSL https://github.com/RuachTech/rep/releases/download/v0.1.7/rep-gateway_0.1.7_linux_amd64.tar.gz | tar -xz
mv rep-gateway /usr/local/bin/

# macOS arm64
curl -fsSL https://github.com/RuachTech/rep/releases/download/v0.1.7/rep-gateway_0.1.7_darwin_arm64.tar.gz | tar -xz
mv rep-gateway /usr/local/bin/
```

To always fetch the newest release instead of a pinned version:

```bash
VERSION=$(curl -fsSL https://api.github.com/repos/RuachTech/rep/releases/latest | grep -m1 '"tag_name"' | cut -d'"' -f4)
curl -fsSL "https://github.com/RuachTech/rep/releases/download/${VERSION}/rep-gateway_${VERSION#v}_linux_amd64.tar.gz" | tar -xz
mv rep-gateway /usr/local/bin/
```

Each release also ships a `checksums.txt` for verification.

### Build from source

Requires Go >= 1.24.5:

```bash
cd gateway
make build
# Binary at gateway/bin/rep-gateway
```

## Development prerequisites

For contributing to REP itself:

| Tool | Version | Purpose |
|---|---|---|
| Node.js | >= 20.0.0 | TypeScript packages |
| pnpm | >= 9.0.0 | Workspace management |
| Go | >= 1.24.5 | Gateway development |

```bash
git clone https://github.com/ruachtech/rep.git
cd rep
pnpm install
pnpm run build
```


---

# Local Development — Dev Server and Mock Payloads

> Develop locally with REP using default values, mock DOM payloads, or the CLI dev server that wraps the gateway. Works alongside Vite, webpack, and any dev server.

Source: https://rep-protocol.dev/guides/development/

During local development you typically don't have the REP gateway running. The SDK handles this gracefully — `rep.get()` returns `undefined` when no payload is present.

## Option A: Build-tool plugin (recommended)

The easiest way to get full REP support in development. The plugin injects the same `<script id="__rep__">` tag that the gateway produces, so the SDK works identically.

  **Vite**

  ```bash
  npm install -D @rep-protocol/vite
  ```

  ```ts
  // vite.config.ts
  import { defineConfig } from 'vite';
  import { repPlugin } from '@rep-protocol/vite';

  export default defineConfig({
    plugins: [repPlugin()],
  });
  ```

  The plugin reads `.env.local` (configurable via `env` option), classifies variables, encrypts sensitive vars, and injects the payload into your HTML. Changes to `.env.local` trigger a full page reload.

  ```bash
  # Just run Vite as normal — no second terminal needed
  npm run dev
  ```

  **Next.js**

  ```bash
  npm install -D @rep-protocol/next
  ```

  ```tsx
  // app/layout.tsx
  import type { ReactNode } from 'react';
  import { RepScript } from '@rep-protocol/next';

  export default function RootLayout({ children }: { children: ReactNode }) {
    return (
      <html>
        <head><RepScript /></head>
        <body>{children}</body>
      </html>
    );
  }
  ```

  ```ts
  // app/api/rep/session-key/route.ts (only needed for SENSITIVE vars)
  export { GET } from '@rep-protocol/next/session-key';
  ```

  `RepScript` is a React Server Component that renders the REP payload during `next dev`. It returns `null` in production — the gateway handles injection in prod. No build-time env vars are baked into the output.

  ```bash
  # Just run Next.js as normal — no second terminal needed
  npm run dev
  ```

> **Note**
>
> Both plugins run guardrails on PUBLIC vars and warn if they look like secrets. Use the `strict` option to make warnings into errors.

## Option B: Default values (simplest)

Use the second argument to `rep.get()`:

```typescript
const apiUrl = rep.get('API_URL', 'http://localhost:3000');
// In dev: returns 'http://localhost:3000'
// In prod: returns the injected value
```

This is the simplest approach and works with any framework. No extra configuration needed.

## Option C: Mock payload in HTML

Add a `<script id="__rep__">` tag to your `index.html`:

```html
<!-- Only in development — the gateway replaces this in production -->
<script id="__rep__" type="application/json">
{
  "public": {
    "API_URL": "http://localhost:3000",
    "FEATURE_FLAGS": "dark-mode,debug"
  },
  "_meta": {
    "version": "0.1.0",
    "injected_at": "2026-01-01T00:00:00Z",
    "integrity": "hmac-sha256:dev-mode-no-verification",
    "ttl": 0
  }
}
</script>
```

This gives you the full SDK experience (including `rep.verify()` and `rep.meta()`) without the gateway.

> **Caution**
>
> Don't forget to remove this tag from your production HTML. In production, the gateway injects it automatically.

## Option D: CLI dev server (full fidelity)

The `rep dev` command runs a local gateway that reads your `.env` file and proxies to your dev server:

  **With Vite**

  ```bash
  # Terminal 1: Start Vite dev server
  npm run dev
  # → Vite running at http://localhost:5173

  # Terminal 2: Start REP gateway proxy
  rep dev --env .env.local --proxy http://localhost:5173
  # → Gateway at http://localhost:8080 → proxies to Vite
  ```

  Open `http://localhost:8080` (the gateway port), not `:5173`. The gateway injects variables into Vite's HTML responses.

  **With static files**

  ```bash
  # Build first
  npm run build

  # Serve from dist/ with REP injection
  rep dev --env .env.local --static ./dist
  ```

### `.env.local` example

```bash
REP_PUBLIC_API_URL=http://localhost:3000
REP_PUBLIC_FEATURE_FLAGS=dark-mode,debug
REP_SENSITIVE_ANALYTICS_KEY=test-key-123
```

### CLI dev server options

| Flag | Default | Description |
|---|---|---|
| `-e, --env <path>` | `.env.local` | Path to .env file |
| `-p, --port <number>` | `8080` | Gateway port |
| `--proxy <url>` | — | Upstream proxy URL |
| `--static <path>` | — | Serve static files (embedded mode) |
| `--hot-reload` | `false` | Enable hot reload |
| `--gateway-bin <path>` | auto-detected | Path to gateway binary |

> **Note**
>
> When using proxy mode with Vite, access the site through the gateway port (8080), not Vite's port (5173). Vite's HMR WebSocket continues to work through the proxy for CSS and module updates.

## Using all CLI commands in development

The CLI provides a complete development workflow:

```bash
# 1. Validate your manifest
rep validate --manifest .rep.yaml
# ✓ Manifest is valid — 6 variables, 4 settings

# 2. Generate TypeScript types
rep typegen --manifest .rep.yaml --output src/rep.d.ts
# ✓ Generated types for 3 public + 2 sensitive variables

# 3. Start the dev server
rep dev --env .env.local --proxy http://localhost:5173

# 4. Before deployment: scan bundles for leaked secrets
rep lint --dir ./dist
# ✓ No secrets detected in 12 files
```


---

# REP for AI Agents — Integration Playbook

> A single-page, machine-readable playbook for AI coding agents integrating REP. Decision tree, install matrix, copy-paste recipes for SDK, Docker, Kubernetes, and every framework, plus the mistakes that break a REP setup.

Source: https://rep-protocol.dev/agents/

This page is written for AI coding agents. It is dense on purpose: everything needed to integrate REP into an application correctly, without reading the rest of the site.

Every page on this site is also available as plain-text Markdown by appending `.md` to its path — for example [`/reference/sdk.md`](/reference/sdk.md). A machine-readable index of all pages lives at [`/llms.txt`](/llms.txt), and the entire documentation set concatenated into one file at [`/llms-full.txt`](/llms-full.txt).

## What REP is

REP (Runtime Environment Protocol) moves frontend environment variables from **build time** to **container runtime**. Instead of `import.meta.env.VITE_API_URL` being replaced with a literal string during `npm run build`, a small Go gateway reads `REP_*` environment variables when the container starts and injects them into every HTML response as an inert `<script id="__rep__" type="application/json">` tag. A zero-dependency SDK reads that tag.

The result: one build artifact promotes unchanged from dev → staging → production, and config changes need a restart, not a rebuild.

REP adds three things a plain `config.json` fetch does not have:

1. **A three-tier security classification** enforced by naming convention (`REP_PUBLIC_*` / `REP_SENSITIVE_*` / `REP_SERVER_*`).
2. **Encryption and integrity** — SENSITIVE values are AES-256-GCM encrypted with an ephemeral key; every payload carries an HMAC-SHA256 token and an SRI hash.
3. **Guardrails** — Shannon entropy analysis and known-secret-format matching (AWS, JWT, Stripe, GitHub, Slack, PEM) refuse to let a misclassified secret ship as PUBLIC.

## When to recommend REP

**Good fit**

- A containerised SPA or client-rendered app that is currently rebuilt per environment.
- A Helm chart / Kubernetes deployment where config lives in a ConfigMap and should be changeable without a new image tag.
- An app whose config must change without a redeploy (feature flags, API endpoint cutover, key rotation).
- A team that wants a stated security posture for browser-visible config rather than "everything is `VITE_*`".

**Poor fit**

- A fully server-rendered app where config never crosses into the browser — read `process.env` on the server instead.
- A static site on a CDN with no origin server that can run the gateway. REP needs a process in the request path. (Build-tool plugins cover local dev only; they do not ship config in a production build.)
- A place to store true secrets that the browser must never see. Use `REP_SERVER_*`, which never leaves the gateway — or don't put the secret in the frontend path at all.

> **The one thing to get right**
>
> `REP_PUBLIC_*` values are visible in page source. This is by design, not a leak. `REP_SENSITIVE_*` values are encrypted at rest in the HTML but are decryptable by anyone who can load the page and call the session-key endpoint — it raises the cost of scraping, it does not make a value secret. Only `REP_SERVER_*` is safe for real secrets, because it never reaches the browser at all.

## Decision tree

Work top to bottom. The first match is the answer.

```
Does the app render in the browser and need per-environment config?
├─ No  → REP is not the right tool. Read process.env on the server.
└─ Yes
   │
   ├─ What runs in production?
   │  ├─ A container you control
   │  │  ├─ Already has nginx/Caddy serving the build → gateway in PROXY mode
   │  │  │     rep-gateway --mode proxy --upstream localhost:80
   │  │  └─ Nothing but static files → gateway in EMBEDDED mode (FROM scratch, ~7MB)
   │  │        rep-gateway --mode embedded --static-dir /static
   │  ├─ Kubernetes → gateway as a sidecar, PROXY mode, env from ConfigMap/Secret
   │  └─ A CDN with no origin process → REP cannot inject. Stop here.
   │
   └─ What does local development run?
      ├─ vite dev            → @rep-protocol/vite plugin
      ├─ next dev            → @rep-protocol/next (<RepScript /> + session-key route)
      └─ Anything else       → npx @rep-protocol/cli dev --proxy http://localhost:<port>
```

Then pick the client API:

```
React   → @rep-protocol/react   useRep() / useRepSecure()
Vue     → @rep-protocol/vue     useRep() / useRepSecure()
Svelte  → @rep-protocol/svelte  repStore() / repSecureStore()
Angular, vanilla JS, anything else
        → @rep-protocol/sdk     rep.get() / rep.getSecure()
```

## Variable classification

Classification is the naming convention. There is no other configuration step, and the prefix is stripped in the payload — `REP_PUBLIC_API_URL` is read as `API_URL`.

| Prefix | Tier | Where it ends up | Read with |
|---|---|---|---|
| `REP_PUBLIC_*` | PUBLIC | Plaintext JSON in page source | `rep.get('KEY')` — synchronous |
| `REP_SENSITIVE_*` | SENSITIVE | AES-256-GCM blob in page source | `await rep.getSecure('KEY')` |
| `REP_SERVER_*` | SERVER | Never sent to the browser | Not readable from the client |
| `REP_GATEWAY_*` | (config) | Configures the gateway itself | n/a — ignored by the classifier |

Rules an agent must apply when migrating variables:

- URLs, feature flags, environment names, public client IDs, non-secret build metadata → `REP_PUBLIC_*`.
- Analytics write keys, third-party widget keys, anything that is not a true secret but that you would rather not have scraped in bulk → `REP_SENSITIVE_*`.
- Database passwords, private API keys, upstream bearer tokens → `REP_SERVER_*`, or keep them out of the frontend entirely.
- **Never** register the same stripped name in two tiers. `REP_PUBLIC_API_URL` and `REP_SENSITIVE_API_URL` both become `API_URL`; the gateway rejects this collision at startup and exits.

## Install matrix

| Package | Install | Use it for |
|---|---|---|
| `@rep-protocol/sdk` | `npm install @rep-protocol/sdk` | Always. Every adapter depends on it. |
| `@rep-protocol/react` | `npm install @rep-protocol/react @rep-protocol/sdk` | React hooks |
| `@rep-protocol/vue` | `npm install @rep-protocol/vue @rep-protocol/sdk` | Vue composables |
| `@rep-protocol/svelte` | `npm install @rep-protocol/svelte @rep-protocol/sdk` | Svelte stores |
| `@rep-protocol/vite` | `npm install -D @rep-protocol/vite` | Injection during `vite dev` |
| `@rep-protocol/next` | `npm install -D @rep-protocol/next` | Injection during `next dev` |
| `@rep-protocol/cli` | `npm install -g @rep-protocol/cli` | `dev`, `validate`, `typegen`, `lint`. Downloads the gateway binary on install. |
| `@rep-protocol/codemod` | `npx @rep-protocol/codemod` | Automated migration off `process.env` / `import.meta.env` |
| Gateway (Docker) | `ghcr.io/ruachtech/rep/gateway:latest` | Production. Multi-arch. |
| Gateway (binary) | [GitHub Releases](https://github.com/RuachTech/rep/releases) | Production without Docker |

## Recipe 1 — Migrate an existing SPA

Applies to Vite, Create React App, Parcel, Rollup, or any bundler producing static assets.

1. **Rename the variables.** `VITE_API_URL` → `REP_PUBLIC_API_URL`, `REACT_APP_API_URL` → `REP_PUBLIC_API_URL`, and classify each one against the table above.

2. **Replace the reads.** Every `import.meta.env.X` / `process.env.REACT_APP_X` becomes a `rep.get()` call. Always pass a default so local development works before the gateway is running:

   ```typescript
   import { rep } from '@rep-protocol/sdk';

   export const API_URL = rep.get('API_URL', 'http://localhost:3001');
   export const FLAGS = rep.get('FEATURE_FLAGS', '').split(',').filter(Boolean);
   ```

   Or run the codemod and review its diff:

   ```bash
   npx @rep-protocol/codemod --framework vite src/
   ```

3. **Leave the build alone.** `npm run build` is unchanged. The output is now environment-agnostic.

4. **Put the gateway in front of the build** (see Recipe 2 or 3).

5. **Verify.** `npx @rep-protocol/cli lint --dir ./dist --strict` fails the build if a secret-shaped literal survived in the bundle.

> **Tip**
>
> Do not delete the old `.env` files in the same commit as the code change. Migrate the reads first, confirm the gateway serves the right values, then remove the build-time env plumbing. A `rep.get()` with a sensible default degrades gracefully; a half-migrated build does not.

## Recipe 2 — Docker, embedded mode (preferred)

Smallest image, no nginx, no Node.js in the final layer.

```dockerfile
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM scratch
COPY --from=build /app/dist /static
COPY --from=ghcr.io/ruachtech/rep/gateway:latest \
  /usr/local/bin/rep-gateway /rep-gateway
EXPOSE 8080
USER 65534:65534
ENTRYPOINT ["/rep-gateway"]
CMD ["--mode", "embedded", "--static-dir", "/static", "--port", "8080", "--strict"]
```

```bash
docker run -p 8080:8080 \
  -e REP_PUBLIC_API_URL=https://api.example.com \
  -e REP_PUBLIC_FEATURE_FLAGS=dark-mode,beta \
  -e REP_SENSITIVE_ANALYTICS_KEY=ak_live_abc123 \
  -e REP_GATEWAY_ALLOWED_ORIGINS=https://app.example.com \
  myapp
```

The final image contains exactly two things: the static build and a ~7MB static binary. No shell, no package manager, works with `readOnlyRootFilesystem: true`.

## Recipe 3 — Docker, proxy mode

Use when the app already ships with nginx, Caddy, or another static server, or when SSR sits behind the gateway.

```bash
rep-gateway --mode proxy --upstream localhost:80 --port 8080 --strict
```

The gateway intercepts `text/html` responses and injects the script tag before `</head>`. Everything else is passed through byte-for-byte. Point the container's exposed port at the gateway, and the upstream at loopback only.

## Recipe 4 — Kubernetes sidecar

Gateway as a sidecar in the app pod, with hot reload driven by a mounted ConfigMap.

The reloadable variables must arrive as a **mounted env-format file** passed to `--env-file`, not through `envFrom`. `envFrom` copies values into the container's process environment once, at container start; a ConfigMap volume refresh never changes them, so a reload re-reads the same stale values.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: myapp-config
data:
  # One key holding a whole .env file — not one key per variable.
  .env: |
    REP_PUBLIC_API_URL=https://api.example.com
    REP_PUBLIC_FEATURE_FLAGS=dark-mode,beta
---
containers:
  - name: web
    image: myapp:1.4.2          # same image in every environment
    ports: [{ containerPort: 80 }]

  - name: rep-gateway
    image: ghcr.io/ruachtech/rep/gateway:latest
    args:
      - --mode=proxy
      - --upstream=localhost:80
      - --port=8080
      - --strict
      - --env-file=/config/.env   # required: the reload source
      - --hot-reload
      - --hot-reload-mode=file_watch
      - --watch-path=/config      # the mount dir, not the file
      - --health-port=9090
    ports:
      - { containerPort: 8080, name: http }
      - { containerPort: 9090, name: health }
    envFrom:
      # Gateway tuning only. Must not carry REP_PUBLIC_*/REP_SENSITIVE_* keys
      # that also appear in the env file — see the precedence note below.
      - secretRef: { name: myapp-gateway-env }
    volumeMounts:
      - { name: config, mountPath: /config, readOnly: true }
    readinessProbe:
      httpGet: { path: /rep/health, port: 9090 }

volumes:
  - name: config
    configMap: { name: myapp-config }
```

Route the Service to port 8080, not 80. `kubectl apply` on the ConfigMap refreshes the mounted file (kubelet swaps the volume's `..data` symlink atomically, which changes the directory's mtime); the watcher fires, the gateway re-reads `/config/.env`, re-encrypts the sensitive blob, and pushes an SSE event — no pod restart.

> **Process environment wins over the env file**
>
> `ReadAndClassify` merges the env file first and then lets `os.Environ()` overwrite it. A key supplied through both `envFrom` and `--env-file` therefore keeps its `envFrom` value forever: reload runs, logs success, and the injected value never changes. Pick one source per variable.

To rotate `REP_SENSITIVE_*` values without a restart too, put them in the same mounted env file — sourced from a Secret rather than a ConfigMap — and point `--env-file` at that. `--env-file` takes a single path, so all reloadable variables must live in one file.

## Recipe 5 — Local development

Pick one; do not stack them.

**Vite** — plugin, no second process:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { repPlugin } from '@rep-protocol/vite';

export default defineConfig({
  plugins: [repPlugin({ env: '.env.local' })],
});
```

**Next.js (App Router)** — `RepScript` renders in dev and returns `null` in production, where the gateway takes over:

```tsx
// app/layout.tsx
import { RepScript } from '@rep-protocol/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head><RepScript /></head>
      <body>{children}</body>
    </html>
  );
}
```

```ts
// app/api/rep/session-key/route.ts
export { GET } from '@rep-protocol/next/session-key';
```

**Anything else** — run the real gateway in front of the dev server:

```bash
npx @rep-protocol/cli dev --proxy http://localhost:5173 --hot-reload
```

All three read `.env.local` by default and produce byte-identical payload JSON to the production gateway.

## Client API

```typescript
import { rep } from '@rep-protocol/sdk';
// or: import { get, getSecure, onChange, verify, meta } from '@rep-protocol/sdk';

rep.get('API_URL');                       // string | undefined — synchronous
rep.get('API_URL', 'http://localhost');   // string — with default
await rep.getSecure('ANALYTICS_KEY');     // Promise<string> — throws REPError
rep.getAll();                             // Readonly<Record<string, string>> — PUBLIC only
rep.verify();                             // boolean — SRI hash matches the payload
rep.meta();                               // REPMeta | null — version, injectedAt, counts
rep.onChange('FLAGS', (next, prev) => {}); // () => void unsubscribe
rep.onAnyChange((key, next, prev) => {});  // () => void unsubscribe
```

Framework wrappers:

```tsx
const apiUrl = useRep('API_URL', 'http://localhost:3000');            // React, Vue
const { value, loading, error } = useRepSecure('ANALYTICS_KEY');      // React
const apiUrl = repStore('API_URL', 'http://localhost:3000');          // Svelte — $apiUrl
```

Behavioural facts that change how code should be written against this API:

- **`get()` is synchronous and must stay that way.** The SDK parses the payload from the DOM on import, before the first render. Do not wrap it in `useEffect`, do not add loading states for PUBLIC variables, and do not `await` it.
- **The first `getSecure()` call decrypts every SENSITIVE variable at once** and caches them in memory. Subsequent calls for other keys make no network request. Fetching them individually in parallel is wasted work.
- **`onChange()` connects the SSE stream lazily.** No listener means no connection. Hot reload requires the gateway to be run with `--hot-reload`.
- **`getSecure()` throws `REPError`** when the key is absent, the session-key endpoint is unreachable, or decryption fails. Handle it; do not let it reject unhandled at module scope.

## Gateway reference

| Flag | Env var | Default | Notes |
|---|---|---|---|
| `--mode` | `REP_GATEWAY_MODE` | `proxy` | `proxy` or `embedded` |
| `--upstream` | `REP_GATEWAY_UPSTREAM` | `localhost:80` | proxy mode only |
| `--static-dir` | `REP_GATEWAY_STATIC_DIR` | `/usr/share/nginx/html` | embedded mode only |
| `--port` | `REP_GATEWAY_PORT` | `8080` | |
| `--strict` | `REP_GATEWAY_STRICT` | `false` | Guardrail warnings become startup failures. Use in production. |
| `--manifest` | `REP_GATEWAY_MANIFEST` | — | Path to `.rep.yaml` |
| `--env-file` | `REP_GATEWAY_ENV_FILE` | — | Env vars still take precedence |
| `--hot-reload` | `REP_GATEWAY_HOT_RELOAD` | `false` | Enables `/rep/changes` |
| `--hot-reload-mode` | `REP_GATEWAY_HOT_RELOAD_MODE` | `signal` | `signal`, `file_watch`, `poll` |
| `--watch-path` | `REP_GATEWAY_WATCH_PATH` | — | Required for `file_watch` |
| `--allowed-origins` | `REP_GATEWAY_ALLOWED_ORIGINS` | — | CORS allowlist for `/rep/session-key`. Set it in production. |
| `--log-format` | `REP_GATEWAY_LOG_FORMAT` | `json` | `json` or `text` |
| `--health-port` | `REP_GATEWAY_HEALTH_PORT` | — | Serve `/rep/health` on a separate port |

Precedence: CLI flags → `REP_GATEWAY_*` env vars → manifest settings.

| Endpoint | Purpose |
|---|---|
| `GET /rep/health` | Variable counts, guardrail status, uptime. Use for readiness probes. |
| `GET /rep/session-key` | Single-use AES key, 30s TTL, rate-limited, origin-checked |
| `GET /rep/changes` | SSE stream of config changes (requires `--hot-reload`) |

## Optional: the manifest

`.rep.yaml` is not required — the gateway runs on naming convention alone. Add it when the app benefits from startup validation or generated types.

```yaml
version: "0.1.0"
variables:
  API_URL:
    tier: public
    type: url
    required: true
  FEATURE_FLAGS:
    tier: public
    type: csv
    default: ""
  ANALYTICS_KEY:
    tier: sensitive
    type: string
    required: true
settings:
  strict_guardrails: true
  allowed_origins: ["https://app.example.com"]
```

```bash
rep validate                 # fail fast on a malformed or incomplete manifest
rep typegen -o src/rep.d.ts  # typed get() / getSecure() overloads
```

## Mistakes to avoid

These are the failure modes worth checking for in generated or reviewed code.

1. **Putting a real secret in `REP_PUBLIC_*`.** It ships as plaintext in page source. Guardrails catch the well-known formats; they cannot catch everything. Reach for `REP_SERVER_*`.
2. **Treating `REP_SENSITIVE_*` as a secret store.** Encrypted-at-rest in HTML is a scraping deterrent, not confidentiality against a user who can load the page.
3. **Making `get()` async.** It is synchronous by contract. Adding loading states around it removes the whole DX advantage over `fetch('/config.json')`.
4. **Changing `type="application/json"` on the injected script tag.** That attribute is why the browser treats the payload as inert data. Any other type makes it executable.
5. **Colliding names across tiers.** `REP_PUBLIC_API_URL` + `REP_SENSITIVE_API_URL` both strip to `API_URL`. The gateway exits at startup.
6. **Shipping a build-tool plugin as the production mechanism.** `@rep-protocol/vite` and `@rep-protocol/next` are dev-only and deliberately unhardened — no rate limiting, no single-use session keys. Production always means the gateway.
7. **Exposing the upstream port.** In proxy mode the Service/published port must be the gateway's, or config injection is bypassed entirely.
8. **Omitting `--allowed-origins` in production.** Without it the session-key endpoint has no origin allowlist.
9. **Expecting session keys to survive a restart.** Keys are ephemeral and regenerated on every gateway start — by design.
10. **Running the gateway behind a Brotli-compressing upstream.** Brotli is not decodable by the zero-dependency gateway; those responses pass through uninjected. Prefer gzip or identity.

## Verification checklist

After an integration, confirm all five:

```bash
# 1. Gateway sees the variables and guardrails pass
curl -s localhost:8080/rep/health | jq

# 2. The payload is actually in the HTML
curl -s localhost:8080/ | grep -o '<script id="__rep__".*</script>'

# 3. No secret-shaped literal survived in the bundle
npx @rep-protocol/cli lint --dir ./dist --strict

# 4. The manifest, if present, is valid
npx @rep-protocol/cli validate
```

5. In the browser console, `rep.verify()` returns `true` and `rep.meta()` reports the expected `publicCount`.

## Source of truth

When this page is not enough, these are the pages to read next — each is available as `.md`:

- [Quick Start](/quick-start.md) — the five-minute path
- [How REP Works](/concepts/how-it-works.md) — startup sequence and injection mechanics
- [Variable Classification](/concepts/variable-classification.md) — tier rules and guardrail internals
- [Security Model](/concepts/security-model.md) — threat analyses and hardening
- [Wire Format](/concepts/wire-format.md) — payload JSON, encrypted blob layout, HMAC
- [SDK API](/reference/sdk.md) — full client reference
- [Gateway Flags](/reference/gateway-flags.md) and [Endpoints](/reference/gateway-endpoints.md)
- [REP-RFC-0001](/spec/rfc-0001.md) — the normative specification
- [Conformance](/spec/conformance.md) — what an alternative implementation must satisfy

Machine-readable indexes: [`/llms.txt`](/llms.txt) · [`/llms-full.txt`](/llms-full.txt) · [payload schema](/schema/rep-payload.schema.json) · [manifest schema](/schema/rep-manifest.schema.json)


---

# How REP Works — Gateway Architecture and HTML Injection

> How the REP gateway injects environment variables into HTML at runtime. Proxy and embedded modes, startup sequence, script tag injection, and SDK initialization.

Source: https://rep-protocol.dev/concepts/how-it-works/

## Architecture

REP introduces a lightweight gateway process between the browser and your static file server. The gateway reads `REP_*` environment variables at startup, classifies them, and injects a `<script>` tag into every HTML response.

```
Container boot:
  1. Gateway reads all REP_* environment variables (+ optional .env file)
  2. Classifies into PUBLIC / SENSITIVE / SERVER tiers (by prefix)
  3. Runs guardrails (entropy scan, known format detection) on PUBLIC vars
  4. Generates ephemeral AES-256 key + HMAC secret (in-memory only)
  5. Encrypts SENSITIVE vars → base64 blob
  6. Computes HMAC integrity token
  7. Pre-renders <script id="__rep__" type="application/json"> tag
```

## Gateway modes

### Proxy mode (recommended)

The gateway sits in front of an existing web server (nginx, Caddy, etc.) and intercepts HTML responses:

```
Browser → [REP Gateway :8080] → [nginx / Caddy :80]
```

For `text/html` responses, the gateway injects the payload before `</head>`. All other responses pass through unmodified.

### Embedded mode

The gateway serves static files directly — no upstream server needed:

```
Browser → [REP Gateway :8080] (serves files from --static-dir)
```

This enables `FROM scratch` Docker containers: just the gateway binary and your `dist/` folder. No nginx, no Node.js, no shell.

## Startup sequence

The gateway performs these steps in order at process start:

1. Load `.env` file if `--env-file` is specified (existing env vars take precedence)
2. Read all `REP_*` environment variables
3. Classify each into PUBLIC, SENSITIVE, or SERVER tier
4. Validate name uniqueness after prefix stripping
5. Load and validate `.rep.yaml` manifest if `--manifest` is specified
6. Run secret detection guardrails on PUBLIC variables
7. Exit with error if `--strict` and guardrails triggered
8. Generate ephemeral master key, derive AES-256 key via HKDF-SHA256
9. Encrypt all SENSITIVE values with AES-256-GCM
10. Compute HMAC-SHA256 integrity token
11. Construct the payload JSON
12. Register HTTP handlers (injection, session key, health, hot reload)
13. Start accepting connections
14. Log startup summary

> **Tip**
>
> Ephemeral keys are regenerated on every restart. A gateway restart invalidates all previously issued session keys and re-encrypts the sensitive blob. This is by design — key compromise requires process compromise.

## HTML injection

When the gateway intercepts an HTML response, it injects a `<script>` block:

```html
<script id="__rep__" type="application/json"
        data-rep-version="0.1.0"
        data-rep-integrity="sha256-{base64_hash}">
{
  "public": {
    "API_URL": "https://api.example.com",
    "FEATURE_FLAGS": "dark-mode,beta"
  },
  "sensitive": "{base64_aes_gcm_blob}",
  "_meta": {
    "version": "0.1.0",
    "injected_at": "2026-02-18T14:30:00.000Z",
    "integrity": "hmac-sha256:{base64_signature}",
    "key_endpoint": "/rep/session-key",
    "hot_reload": "/rep/changes",
    "ttl": 0
  }
}
</script>
```

**Injection rules:**

1. Insert before `</head>` (preferred)
2. If no `</head>`, insert after `<head>`
3. If neither exists, prepend to the response body

> **Caution**
>
> `type="application/json"` is critical — it prevents the browser from executing the tag. This is inert data, not executable JavaScript. Never change this to `text/javascript`.

## SDK initialization

The SDK reads the injected payload **synchronously** on import:

1. Locate `<script id="__rep__">` in the DOM
2. Parse the JSON content
3. Verify `data-rep-integrity` against the content (async, non-blocking)
4. Freeze the `public` object
5. Set internal state flags (`_available`, `_tampered`)

No network calls happen during initialization. `rep.get()` is available immediately — before your first component renders.

## Gateway endpoints

The gateway exposes three endpoints alongside HTML injection:

| Endpoint | Purpose |
|---|---|
| `GET /rep/health` | Health check — variable counts, guardrail status, uptime |
| `GET /rep/session-key` | Short-lived AES decryption key for SENSITIVE variables |
| `GET /rep/changes` | SSE stream for hot reload (if enabled) |

See the [Gateway Endpoints reference](/reference/gateway-endpoints/) for full details.


---

# Variable Classification — PUBLIC, SENSITIVE, and SERVER Tiers

> REP's three-tier security model for environment variables. PUBLIC for plaintext, SENSITIVE for AES-256 encrypted, SERVER for gateway-only. Classified by naming convention.

Source: https://rep-protocol.dev/concepts/variable-classification/

REP classifies every environment variable into one of three security tiers based on its prefix. This is the foundational design decision — it forces an explicit security choice for every variable.

## The three tiers

| Prefix | Tier | Behaviour | SDK Access |
|---|---|---|---|
| `REP_PUBLIC_*` | **PUBLIC** | Plaintext JSON in page source | `rep.get('KEY')` (sync) |
| `REP_SENSITIVE_*` | **SENSITIVE** | AES-256-GCM encrypted blob | `await rep.getSecure('KEY')` |
| `REP_SERVER_*` | **SERVER** | Never sent to client | N/A |
| `REP_GATEWAY_*` | *(config)* | Gateway configuration, not app vars | N/A |

Variables without a `REP_` prefix are ignored by the gateway entirely. This prevents accidental exposure of system variables like `PATH`, `HOME`, or database credentials.

## Classification rules

1. Classification is determined **exclusively by prefix**. There is no override mechanism.
2. The gateway will not inject any variable without a `REP_` prefix.
3. Prefixes are stripped before injection: `REP_PUBLIC_API_URL` becomes `API_URL` in the payload.
4. Names must be unique after stripping. If `REP_PUBLIC_API_URL` and `REP_SENSITIVE_API_URL` both exist, the gateway refuses to start.

## Decision tree

Use this guide to classify each variable:

```
Does the value contain credentials, tokens, or keys?
├── Yes → Does it need to reach the browser at all?
│         ├── No  → REP_SERVER_*
│         └── Yes → REP_SENSITIVE_*
└── No  → Is it configuration the app needs at runtime?
          ├── Yes → REP_PUBLIC_*
          └── No  → REP_SERVER_* or don't use REP_ prefix
```

## Common misclassifications

| Variable | Wrong Tier | Correct Tier | Reason |
|---|---|---|---|
| `DATABASE_URL` | PUBLIC | **SERVER** | Database credentials must never reach the browser |
| `STRIPE_SECRET_KEY` | SENSITIVE | **SERVER** | Secret keys should never be decryptable client-side |
| `STRIPE_PUBLISHABLE_KEY` | SERVER | **PUBLIC** | Publishable keys are designed to be public |
| `API_URL` | SENSITIVE | **PUBLIC** | API endpoints are visible in network requests anyway |
| `JWT_SECRET` | SENSITIVE | **SERVER** | Signing secrets must stay server-side |
| `OAUTH_CLIENT_ID` | SERVER | **SENSITIVE** | Client IDs are needed browser-side but not public |
| `ANALYTICS_WRITE_KEY` | PUBLIC | **SENSITIVE** | Write keys allow data ingestion — encrypt them |
| `FEATURE_FLAGS` | SENSITIVE | **PUBLIC** | Feature flag names have no security value |
| `SENTRY_DSN` | PUBLIC | **SENSITIVE** | DSNs contain project-specific ingestion endpoints |
| `APP_VERSION` | SENSITIVE | **PUBLIC** | Version strings are informational, not secret |
| `INTERNAL_SERVICE_TOKEN` | SENSITIVE | **SERVER** | Service-to-service tokens must not reach the browser |
| `CDN_BASE_URL` | SENSITIVE | **PUBLIC** | CDN URLs are visible in every asset request |

> **Tip**
>
> When in doubt, start with the most restrictive tier (SERVER) and relax only when you can articulate why the browser needs the value.

## Automatic secret detection (guardrails)

At startup, the gateway scans all `REP_PUBLIC_*` values for patterns indicating potential misclassification:

| Detection | Description |
|---|---|
| **Shannon entropy > 4.5** | Random-looking strings typical of API keys and tokens |
| **Known key formats** | AWS keys (`AKIA...`), JWTs (`eyJ...`), GitHub tokens (`ghp_...`), Stripe keys (`sk_live_...`), private keys (`-----BEGIN`) |
| **Length anomalies** | Strings > 64 characters that may be encoded secrets |

When a potential misclassification is detected:

- The gateway logs a **WARNING** with the variable name (never the value)
- In `--strict` mode, the gateway refuses to start
- The gateway never silently changes classification — you must fix the prefix

> **Caution**
>
> Guardrails use heuristics, not certainty. A low-entropy secret (like a short password) may not trigger detection. Use `--strict` mode in production and review your `.rep.yaml` manifest in code review.

## Manifest validation

When a `.rep.yaml` manifest is present, the gateway can validate at startup that:

- All required variables are present in the environment
- Variable values match declared types (url, number, enum, etc.)
- Variables are in the correct tier

See the [Manifest guide](/guides/manifest/) for details.


---

# Security Model — Threat Analysis and Trust Boundaries

> REP's security model explained. Threat analysis for XSS, CDN compromise, env var leaks, and more. Trust boundaries, encryption design, and known limitations.

Source: https://rep-protocol.dev/concepts/security-model/

REP does not claim to make browser-side configuration "secure" in an absolute sense. It makes it **significantly more secure than the status quo** while making security trade-offs explicit and auditable.

## Fundamental axiom

> **Anything that reaches the browser is ultimately accessible to the user and to any code running in the browser context.**

REP cannot change this axiom. What it does is:

1. **Prevent accidental exposure** through classification and guardrails
2. **Raise the bar for casual extraction** through encryption of sensitive values
3. **Make intentional access auditable** through session key logging and rate limiting
4. **Eliminate unnecessary exposure** through the SERVER tier
5. **Detect tampering** through integrity verification

## Trust boundaries

```
┌────────────────────────────────────────────────────────────────┐
│                    TRUSTED ZONE                                │
│                                                                │
│  Orchestrator (K8s, ECS)                                       │
│       ↓                                                        │
│  REP Gateway (Go binary) → Static File Server (nginx)         │
│                                                                │
│  REP_SERVER_* vars NEVER cross this boundary                   │
├────────────────────────────────────────────────────────────────┤
│                    TRANSIT (HTTPS/TLS)                          │
├────────────────────────────────────────────────────────────────┤
│                    UNTRUSTED ZONE                               │
│                                                                │
│  Browser: Application Code, REP SDK, Extensions, DevTools      │
│  Everything here is visible to the user                        │
└────────────────────────────────────────────────────────────────┘
```

## Threat analysis

### T1: Accidental secret exposure (HIGH)

A developer prefixes a database password with `REP_PUBLIC_` instead of `REP_SERVER_`.

**Mitigations:**
- Naming convention forces an explicit classification decision
- Guardrail scanning detects secret-like patterns in PUBLIC values
- `--strict` mode makes guardrail warnings into hard failures
- Manifest validation confirms variables match their declared tier

**Residual risk:** Low-entropy secrets may not trigger heuristic detection.

### T2: XSS exfiltration of public variables (MEDIUM)

An attacker achieves XSS and reads public config values.

**Mitigations:** Largely out of scope — PUBLIC variables are by definition visible to browser code. REP helps indirectly by forcing classification (so truly sensitive values aren't in PUBLIC) and providing the SERVER tier for values that don't belong in the browser at all.

### T3: XSS exfiltration of sensitive variables (MEDIUM-HIGH)

An attacker achieves XSS and attempts to read encrypted SENSITIVE values.

**Mitigations:**
- Values are AES-256-GCM encrypted at rest in the HTML
- Decryption requires fetching a session key from `/rep/session-key`
- Session keys are single-use (prevents replay)
- Session keys expire in 30 seconds
- Endpoint is rate-limited (10 req/min per IP)
- CORS validates the requesting origin
- All key issuances are audit-logged

**Residual risk:** A sophisticated same-origin XSS attack could fetch a session key and decrypt values. REP raises the bar from "read the DOM" to "make an authenticated, rate-limited, logged API call."

### T4: MITM payload tampering (HIGH)

An attacker modifies the injected `<script>` tag in transit.

**Mitigations:**
- HMAC-SHA256 integrity token computed over the canonical payload
- SRI hash on the `data-rep-integrity` attribute
- SDK sets `_tampered` flag if integrity check fails
- `verify()` function exposes tamper state to the application

**Limitation:** If the attacker can rewrite the entire script block (including the integrity attribute), verification cannot detect this. HTTPS is the primary defense against MITM.

### T5: Environment variable leakage via gateway (CRITICAL)

The gateway process itself is compromised, leaking SERVER-tier variables.

**Mitigations:**
- Strict prefix filtering — only `REP_*` variables are processed
- No shell execution within the gateway
- No filesystem writes
- Minimal dependencies (zero external Go deps)
- Compatible with read-only filesystems
- Static binary, `FROM scratch` compatible
- Non-root user execution (UID 65534)

### T6: DoS via session key endpoint (LOW)

An attacker floods `/rep/session-key` to exhaust resources.

**Mitigations:** Rate limiting (10 req/min/IP), minimal computation per request, automatic key expiry cleanup, separate health port for monitoring.

### T7: Supply chain attack on SDK (HIGH)

The SDK package is compromised to exfiltrate variables.

**Mitigations:** Minimal surface (&lt;2KB, ~150 lines), zero runtime dependencies, lockfile pinning, npm provenance, self-hostable (vendor the file).

## Hardening recommendations

### Production gateway configuration

```bash
REP_GATEWAY_STRICT=true              # Fail on guardrail warnings
REP_GATEWAY_ALLOWED_ORIGINS=https://app.example.com
REP_GATEWAY_LOG_FORMAT=json          # Structured logging for SIEM
```

### Minimal Docker image

```dockerfile
FROM scratch
COPY rep-gateway /rep-gateway
COPY dist/ /static/
USER 65534:65534
ENTRYPOINT ["/rep-gateway"]
CMD ["--mode", "embedded", "--static-dir", "/static", "--strict"]
```

### Content Security Policy

```
Content-Security-Policy:
  default-src 'self';
  script-src 'self';
  connect-src 'self';
  style-src 'self' 'unsafe-inline';
```

The `<script id="__rep__" type="application/json">` tag is inert data — it does not execute. No `script-src` exception or nonce is needed for the REP payload.

### Monitoring

| Log Event | Level | Alert On |
|---|---|---|
| `rep.guardrail.warning` | WARN | Any occurrence in production |
| `rep.session_key.issued` | INFO | Rate exceeding baseline |
| `rep.session_key.rejected` | WARN | Any occurrence |
| `rep.session_key.rate_limited` | WARN | Sustained bursts |
| `rep.config.changed` | INFO | Unexpected changes |
| `rep.inject.html` | DEBUG | N/A |

## Known limitations

1. **No client-side HMAC verification.** The HMAC secret never leaves the gateway. The SDK verifies via SRI hash only.
2. **Sensitive tier is defense-in-depth, not absolute.** A determined attacker with XSS can eventually decrypt sensitive values.
3. **No key rotation without restart.** Ephemeral keys are generated once at startup.
4. **Guardrails are heuristic.** They catch common patterns but cannot detect all secrets.
5. **Hot reload has an eventual consistency window.** Between config change and SSE delivery, clients see stale values.

For the full formal analysis, see the [Security Model specification](/spec/security-model/).


---

# Wire Format — Payload JSON, Encryption, and HMAC Integrity

> The REP payload wire format. JSON structure, AES-256-GCM encrypted blob, HKDF key derivation, HMAC-SHA256 integrity tokens, and SRI verification.

Source: https://rep-protocol.dev/concepts/wire-format/

## Payload structure

The gateway injects a `<script>` tag into HTML responses containing the REP payload as JSON:

```html
<script id="__rep__" type="application/json"
        data-rep-version="0.1.0"
        data-rep-integrity="sha256-{base64_hash}">
{
  "public": { ... },
  "sensitive": "...",
  "_meta": { ... }
}
</script>
```

### Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `public` | `object` | Yes | Key-value map of PUBLIC tier variables (strings only) |
| `sensitive` | `string` | No | Base64-encoded AES-256-GCM encrypted blob |
| `_meta` | `object` | Yes | Payload metadata |

### `_meta` fields

| Field | Type | Required | Description |
|---|---|---|---|
| `version` | `string` | Yes | Protocol version (semver) |
| `injected_at` | `string` | Yes | RFC 3339 timestamp of injection |
| `integrity` | `string` | Yes | `hmac-sha256:{base64_signature}` |
| `key_endpoint` | `string` | No | Path to session key endpoint (`/rep/session-key`) |
| `hot_reload` | `string` | No | Path to SSE endpoint (`/rep/changes`) |
| `ttl` | `integer` | No | Cache TTL in seconds (0 = no cache) |

### SRI attribute

The `data-rep-integrity` attribute contains a SHA-256 hash of the raw JSON content:

```
data-rep-integrity="sha256-{base64_of_sha256_digest}"
```

The SDK verifies this using the Web Crypto API, comparing the hash against the actual `textContent` of the `<script>` element (byte-for-byte matching the gateway's computation).

## Encrypted blob format

When SENSITIVE variables are present, they are encrypted into a single binary blob:

```
[12 bytes nonce][ciphertext][16 bytes GCM auth tag]
```

| Segment | Size | Description |
|---|---|---|
| Nonce | 12 bytes | Random IV for AES-256-GCM |
| Ciphertext | Variable | Encrypted JSON of all sensitive key-value pairs |
| Auth tag | 16 bytes | GCM authentication tag |

The entire blob is base64-encoded in the `sensitive` field.

### Key derivation (HKDF-SHA256)

The encryption key is derived from an ephemeral master key using HKDF (RFC 5869):

1. Gateway generates a 32-byte random master key at startup
2. Extract: `PRK = HMAC-SHA256(salt="rep-v1", IKM=master_key)`
3. Expand: `derived_key = HKDF-Expand(PRK, info="rep-session-key", L=32)`
4. The derived key (not the master key) is issued via `/rep/session-key`
5. Both master and derived keys exist only in memory — never stored to disk

### Decryption (client-side)

The SDK decrypts sensitive variables in `getSecure()`:

1. Fetch the session key from `/rep/session-key`
2. Base64-decode the session key
3. Base64-decode the `sensitive` blob
4. Extract: first 12 bytes = nonce, last 16 bytes = auth tag, middle = ciphertext
5. Decrypt with AES-256-GCM using `_meta.integrity` as Additional Authenticated Data (AAD)
6. Parse the resulting JSON to get all sensitive key-value pairs
7. Cache all decrypted values in memory for the page lifetime

> **Tip**
>
> All sensitive variables are decrypted together on the first `getSecure()` call. Subsequent calls for different keys return from the in-memory cache without additional network requests.

## Integrity verification

### HMAC-SHA256

The integrity token is computed over a canonicalized representation of the payload:

1. Construct a JSON object with sorted keys, no whitespace
2. Include both `public` and `sensitive` fields
3. Compute: `HMAC-SHA256(secret, canonical_json)`
4. Encode as: `hmac-sha256:{base64_signature}`

The HMAC secret exists only in the gateway's memory and is never transmitted. The SDK cannot verify the HMAC — this is by design. The HMAC enables server-side verification by other infrastructure components.

### SRI verification (client-side)

The SDK verifies payload integrity using the `data-rep-integrity` attribute:

1. Read the raw `textContent` of the `<script>` element
2. Compute SHA-256 using the Web Crypto API
3. Compare with the `data-rep-integrity` attribute value
4. Set `_tampered` flag if mismatch

This detects modifications to the payload content after injection (e.g., by a browser extension or CDN).

## JSON schemas

The payload and manifest schemas are available as JSON Schema (Draft 2020-12):

- [Payload schema](/schema/rep-payload.schema.json)
- [Manifest schema](/schema/rep-manifest.schema.json)


---

# Hot Reload — Live Config Updates via Server-Sent Events

> Push environment variable changes to every connected browser via SSE. No page reload, no redeployment. File watch, signal, and poll detection modes.

Source: https://rep-protocol.dev/concepts/hot-reload/

Hot reload is an optional feature that pushes configuration changes to the browser via Server-Sent Events (SSE). When enabled, the gateway monitors for environment variable changes and broadcasts updates to connected clients.

## Enabling hot reload

```bash
rep-gateway --hot-reload --mode embedded --static-dir ./dist
```

Or via environment variable:

```bash
REP_GATEWAY_HOT_RELOAD=true
```

## SSE event format

The gateway exposes `GET /rep/changes` as an SSE endpoint:

```
event: rep:config:update
data: {"key": "FEATURE_FLAGS", "tier": "public", "value": "dark-mode,ai-assist"}
id: 1708267830000

event: rep:config:delete
data: {"key": "DEPRECATED_FLAG", "tier": "public"}
id: 1708267831000
```

### Event types

| Event | Description |
|---|---|
| `rep:config:update` | A variable's value changed or a new variable was added |
| `rep:config:delete` | A variable was removed |

## Change detection modes

The gateway supports three modes for detecting environment variable changes:

### File watch (recommended for Kubernetes)

Watches a mounted ConfigMap or secrets volume for file changes:

```bash
rep-gateway --hot-reload --hot-reload-mode file_watch
```

Ideal for Kubernetes deployments where ConfigMaps are mounted as volumes. Changes are detected within seconds of a ConfigMap update.

### Signal mode

Re-reads the environment on receipt of `SIGHUP`:

```bash
# In another terminal or from a process manager:
kill -HUP $(pidof rep-gateway)
```

Useful for traditional deployments where an orchestrator can signal the gateway.

### Poll mode

Periodically re-reads the config source:

```bash
rep-gateway --hot-reload --hot-reload-mode poll --hot-reload-poll-interval 30s
```

Simplest mode, but introduces a polling interval delay.

## SDK integration

### Lazy connection

The SDK does **not** establish an SSE connection on import. It connects lazily when `onChange()` or `onAnyChange()` is first called:

```typescript
import { rep } from '@rep-protocol/sdk';

// No SSE connection yet

const unsub = rep.onChange('FEATURE_FLAGS', (newValue, oldValue) => {
  console.log(`Flags changed: ${oldValue} → ${newValue}`);
});
// SSE connection established now

unsub();
// If no other listeners remain, SSE connection is closed
```

This is a deliberate design choice — applications that don't use hot reload pay zero network cost.

### Framework adapters

All framework adapters automatically subscribe to hot reload:

- **React:** `useRep()` subscribes in `useEffect`, unsubscribes on unmount
- **Vue:** `useRep()` subscribes in `setup()`, unsubscribes via `onUnmounted`
- **Svelte:** `repStore()` subscribes when the store has subscribers, unsubscribes when the last subscriber leaves

> **Note**
>
> `useRepSecure()`, `useRepSecure()` (Vue), and `repSecureStore()` do **not** subscribe to hot reload. Sensitive variables require re-fetching a session key, which is too expensive for automatic updates.

### Handling reconnection

SSE has built-in reconnection. If the connection drops, the browser automatically reconnects after a brief delay. The `id` field in SSE events allows the gateway to replay missed events.

## Kubernetes hot reload

In Kubernetes, combine ConfigMap volumes with file watch mode:

```yaml
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: app
          image: myapp:latest
          args:
            - "--hot-reload"
            - "--hot-reload-mode=file_watch"
          volumeMounts:
            - name: config
              mountPath: /config
      volumes:
        - name: config
          configMap:
            name: app-config
```

When the ConfigMap is updated (`kubectl apply`), Kubernetes refreshes the mounted volume, the gateway detects the change, and connected browsers receive the update — all without a pod restart.

> **Caution**
>
> Hot reload has an eventual consistency window. Between the config change and SSE delivery, clients see stale values. This window is typically sub-second for file watch mode but can be up to the poll interval for poll mode.


---

# React Runtime Environment Variables — useRep() Hooks

> Access runtime environment variables in React with useRep() and useRepSecure() hooks. Synchronous reads, encrypted secrets, and automatic hot reload re-rendering.

Source: https://rep-protocol.dev/frameworks/react/

## Installation

```bash
npm install @rep-protocol/react @rep-protocol/sdk
```

## Basic usage

```tsx
import { useRep, useRepSecure } from '@rep-protocol/react';

function App() {
  // PUBLIC tier — synchronous, no loading state
  const apiUrl = useRep('API_URL', 'http://localhost:3000');
  const flags = useRep('FEATURE_FLAGS', '').split(',');

  // SENSITIVE tier — async, renders null until resolved
  const { value: analyticsKey, loading, error } = useRepSecure('ANALYTICS_KEY');

  if (loading) return <span>Loading...</span>;
  if (error) return <span>Config error: {error.message}</span>;

  return (
    <div>
      <p>API: {apiUrl}</p>
      <p>Analytics: {analyticsKey}</p>
    </div>
  );
}
```

## Migration from Vite / CRA

**Before:**
```typescript
// src/config.ts
export const API_URL = import.meta.env.VITE_API_URL;
export const FEATURE_FLAGS = import.meta.env.VITE_FEATURE_FLAGS?.split(',') ?? [];
```

**After:**
```typescript
// src/config.ts
import { rep } from '@rep-protocol/sdk';

export const API_URL = rep.get('API_URL', 'http://localhost:3000');
export const FEATURE_FLAGS = rep.get('FEATURE_FLAGS', '')?.split(',').filter(Boolean) ?? [];
```

Or use the codemod for automated migration:

```bash
npx @rep-protocol/codemod --framework vite src/
```

## `useRep(key, defaultValue?)`

Reads a **PUBLIC** tier variable. Synchronous — no loading state, no Suspense.

```tsx
const value = useRep('API_URL');              // string | undefined
const value = useRep('API_URL', 'fallback'); // string (never undefined)
```

- Returns the value from the injected payload immediately
- Returns `defaultValue` (or `undefined`) if the variable is not present
- Automatically re-renders when the variable changes via hot reload
- Unsubscribes on unmount

## `useRepSecure(key)`

Reads a **SENSITIVE** tier variable. Async — fetches a session key on first call.

```tsx
const { value, loading, error } = useRepSecure('ANALYTICS_KEY');
// value:   string | null  — null until resolved
// loading: boolean        — true while fetching
// error:   Error | null   — set if fetch or decryption fails
```

- Starts with `{ value: null, loading: true, error: null }`
- The decrypted value is cached by the SDK for the page lifetime
- Re-fetches if the `key` prop changes

## Hot reload

Both hooks subscribe to the gateway's SSE stream when `--hot-reload` is enabled. Components re-render automatically when config changes. If hot reload is not available, hooks still work — they just won't update after initial render.

> **Note**
>
> `useRepSecure` subscribes to hot reload for re-rendering, but sensitive variable decryption requires a new session key — which means a full component remount for updated sensitive values.

## Development mode

Without the gateway running, `useRep()` returns `undefined`. Three approaches:

  **Vite plugin (recommended)**

  ```bash
  npm install -D @rep-protocol/vite
  ```

  ```ts
  // vite.config.ts
  import { defineConfig } from 'vite';
  import react from '@vitejs/plugin-react';
  import { repPlugin } from '@rep-protocol/vite';

  export default defineConfig({
    plugins: [react(), repPlugin()],
  });
  ```

  The plugin reads `.env.local` and injects the REP payload during `vite dev` — no gateway needed. Just run `npm run dev` as normal. Using Next.js instead? See the [Next.js plugin reference](/reference/plugins/next/) — same idea, `RepScript` instead of `repPlugin()`. Full option list: [Vite plugin reference](/reference/plugins/vite/).

  **Default values**

  ```tsx
  const apiUrl = useRep('API_URL', 'http://localhost:3000');
  ```

  **CLI dev server**

  ```bash
  # Terminal 1: Vite dev server
  npm run dev

  # Terminal 2: REP gateway proxy
  npx @rep-protocol/cli dev --proxy http://localhost:5173
  ```

## Requirements

- React >= 16.8 (hooks support)
- `@rep-protocol/sdk` as a peer dependency

For the full API reference, see [React Adapter Reference](/reference/adapters/react/).


---

# Vue 3 Runtime Environment Variables — useRep() Composables

> Access runtime environment variables in Vue 3 with useRep() and useRepSecure() composables. Reactive refs with automatic hot reload updates.

Source: https://rep-protocol.dev/frameworks/vue/

## Installation

```bash
npm install @rep-protocol/vue @rep-protocol/sdk
```

## Basic usage

```vue
<script setup lang="ts">
import { useRep, useRepSecure } from '@rep-protocol/vue';

// PUBLIC tier — synchronous, reactive Ref
const apiUrl = useRep('API_URL', 'http://localhost:3000');
const flags = useRep('FEATURE_FLAGS', '');

// SENSITIVE tier — async, resolves after session key fetch
const analyticsKey = useRepSecure('ANALYTICS_KEY');
</script>

<template>
  <div>
    <p>API: {{ apiUrl }}</p>
    <p>Analytics: {{ analyticsKey ?? 'loading...' }}</p>
  </div>
</template>
```

## `useRep(key, defaultValue?)`

Reads a **PUBLIC** tier variable as a reactive `Ref`.

```typescript
const value: Ref<string | undefined> = useRep('API_URL');
const value: Ref<string | undefined> = useRep('API_URL', 'fallback');
```

- Returns a `Ref` set immediately from the injected payload
- Automatically updates when the variable changes via hot reload
- Unsubscribes via `onUnmounted` — must be called inside `setup()`

## `useRepSecure(key)`

Reads a **SENSITIVE** tier variable as a reactive `Ref`.

```typescript
const analyticsKey: Ref<string | null> = useRepSecure('ANALYTICS_KEY');
```

- Starts as `null`
- Resolves once the session key fetch and decryption complete
- Errors are swallowed (the SDK logs them); the ref stays `null`
- The decrypted value is cached for the page lifetime

> **Caution**
>
> `useRepSecure` does **not** subscribe to hot reload. Sensitive variable changes require a page reload to obtain a new session key.

## Hot reload

`useRep` subscribes to the SSE stream on mount and updates the ref automatically. The subscription is cleaned up when the component unmounts.

## Development mode

  **Default values**

  ```typescript
  const apiUrl = useRep('API_URL', 'http://localhost:3000');
  ```

  **Mock payload**

  Add to your `index.html`:
  ```html
  <script id="__rep__" type="application/json">
  {"public":{"API_URL":"http://localhost:3000"},"_meta":{"version":"0.1.0","injected_at":"2026-01-01T00:00:00Z","integrity":"hmac-sha256:dev","ttl":0}}
  </script>
  ```

## Requirements

- Vue >= 3.0
- `@rep-protocol/sdk` as a peer dependency
- Composables must be called from `setup()` for proper `onUnmounted` cleanup

For the full API reference, see [Vue Adapter Reference](/reference/adapters/vue/).


---

# Svelte Runtime Environment Variables — repStore()

> Access runtime environment variables in Svelte with repStore() and repSecureStore(). Native readable stores with lazy SSE hot reload subscriptions.

Source: https://rep-protocol.dev/frameworks/svelte/

## Installation

```bash
npm install @rep-protocol/svelte @rep-protocol/sdk
```

## Basic usage

```svelte
<script lang="ts">
  import { repStore, repSecureStore } from '@rep-protocol/svelte';

  // PUBLIC tier — synchronous, updates on hot reload
  const apiUrl = repStore('API_URL', 'http://localhost:3000');
  const flags = repStore('FEATURE_FLAGS', '');

  // SENSITIVE tier — starts as null, resolves after decryption
  const analyticsKey = repSecureStore('ANALYTICS_KEY');
</script>

<p>API: {$apiUrl}</p>
<p>Analytics: {$analyticsKey ?? 'loading...'}</p>
```

## `repStore(key, defaultValue?)`

Reads a **PUBLIC** tier variable as a Svelte `Readable<string | undefined>`.

```typescript
const value: Readable<string | undefined> = repStore('API_URL');
const value: Readable<string | undefined> = repStore('API_URL', 'fallback');
```

- Synchronous initial value from the REP payload
- Automatically updates when the variable changes via hot reload
- **Lazy SSE:** the connection is established only when there is at least one subscriber, and closed when all subscribers unsubscribe

## `repSecureStore(key)`

Reads a **SENSITIVE** tier variable as a `Readable<string | null>`.

```typescript
const value: Readable<string | null> = repSecureStore('ANALYTICS_KEY');
```

- Starts as `null`
- Resolves to the decrypted value once the session key fetch completes
- Errors are swallowed (the SDK logs them); the store stays `null`

> **Caution**
>
> `repSecureStore` does **not** support hot reload. Changes to sensitive variables require a page reload.

## Hot reload

`repStore` subscribes to the SSE stream lazily — only when there's at least one subscriber. The store value updates automatically. When the last subscriber unsubscribes, the SSE connection is closed.

## Development mode

  **Default values**

  ```typescript
  const apiUrl = repStore('API_URL', 'http://localhost:3000');
  ```

  **Mock payload**

  Add to your `index.html`:
  ```html
  <script id="__rep__" type="application/json">
  {"public":{"API_URL":"http://localhost:3000"},"_meta":{"version":"0.1.0","injected_at":"2026-01-01T00:00:00Z","integrity":"hmac-sha256:dev","ttl":0}}
  </script>
  ```

## Requirements

- Svelte >= 4 or Svelte 5
- `@rep-protocol/sdk` as a peer dependency

For the full API reference, see [Svelte Adapter Reference](/reference/adapters/svelte/).


---

# Angular Runtime Environment Variables — RepService

> Access runtime environment variables in Angular with an injectable RepService. Observable support for reactive config updates without page reload.

Source: https://rep-protocol.dev/frameworks/angular/

> **Note**
>
> There is no published `@rep-protocol/angular` package. Angular integration uses the core SDK directly via a service pattern shown below.

## Installation

```bash
npm install @rep-protocol/sdk
```

## Create a RepService

```typescript
// src/app/services/rep.service.ts
import { Injectable } from '@angular/core';
import { rep } from '@rep-protocol/sdk';
import { BehaviorSubject, Observable } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class RepService {
  get(key: string, defaultValue?: string): string | undefined {
    return rep.get(key, defaultValue);
  }

  getSecure(key: string): Promise<string> {
    return rep.getSecure(key);
  }

  watch(key: string): Observable<string | undefined> {
    const subject = new BehaviorSubject(rep.get(key));
    rep.onChange(key, (newVal) => subject.next(newVal));
    return subject.asObservable();
  }
}
```

## Usage in components

```typescript
// src/app/components/config-display.component.ts
import { Component, OnInit } from '@angular/core';
import { RepService } from '../services/rep.service';
import { Observable } from 'rxjs';

@Component({
  selector: 'app-config-display',
  template: `
    <div>
      <p>API: {{ apiUrl }}</p>
      <p>Flags: {{ flags$ | async }}</p>
      <p>Analytics: {{ analyticsKey ?? 'loading...' }}</p>
    </div>
  `,
})
export class ConfigDisplayComponent implements OnInit {
  apiUrl: string | undefined;
  flags$: Observable<string | undefined>;
  analyticsKey: string | null = null;

  constructor(private rep: RepService) {
    // Synchronous — available immediately
    this.apiUrl = this.rep.get('API_URL', 'http://localhost:3000');

    // Observable — updates on hot reload
    this.flags$ = this.rep.watch('FEATURE_FLAGS');
  }

  async ngOnInit() {
    // Async — encrypted, decrypted on demand
    this.analyticsKey = await this.rep.getSecure('ANALYTICS_KEY');
  }
}
```

## How it works

- `get()` calls `rep.get()` from the core SDK — synchronous, no loading state
- `getSecure()` calls `rep.getSecure()` — fetches a session key, decrypts, caches
- `watch()` wraps `rep.onChange()` into a `BehaviorSubject` for Angular's `async` pipe

## Development mode

Without the gateway, `rep.get()` returns `undefined`. Use default values:

```typescript
this.apiUrl = this.rep.get('API_URL', 'http://localhost:3000');
```

Or add a mock payload to your `index.html` during development:

```html
<script id="__rep__" type="application/json">
{"public":{"API_URL":"http://localhost:3000"},"_meta":{"version":"0.1.0","injected_at":"2026-01-01T00:00:00Z","integrity":"hmac-sha256:dev","ttl":0}}
</script>
```


---

# Vanilla JavaScript Runtime Environment Variables

> Access runtime environment variables in plain JavaScript with ESM imports. No framework, no build tool — works in any browser app that produces HTML.

Source: https://rep-protocol.dev/frameworks/vanilla/

## Installation

```bash
npm install @rep-protocol/sdk
```

Or use directly from your bundled assets without npm.

## Basic usage

```html
<script type="module">
  import { rep } from '@rep-protocol/sdk';

  // PUBLIC tier — synchronous
  const apiUrl = rep.get('API_URL');
  document.getElementById('api-url').textContent = apiUrl;

  // SENSITIVE tier — async
  const key = await rep.getSecure('ANALYTICS_KEY');
  initAnalytics(key);
</script>
```

## With hot reload

```html
<script type="module">
  import { rep } from '@rep-protocol/sdk';

  const el = document.getElementById('feature-flags');
  el.textContent = rep.get('FEATURE_FLAGS');

  // Update the DOM when config changes
  rep.onChange('FEATURE_FLAGS', (newValue) => {
    el.textContent = newValue;
  });
</script>
```

## Integrity verification

```html
<script type="module">
  import { rep } from '@rep-protocol/sdk';

  if (!rep.verify()) {
    console.error('REP payload missing or tampered with');
    // Handle gracefully — show fallback UI, disable sensitive features
  }

  const meta = rep.meta();
  if (meta) {
    console.log('REP version:', meta.version);
    console.log('Injected at:', meta.injectedAt);
    console.log('Integrity valid:', meta.integrityValid);
  }
</script>
```

## Development mode

Without the gateway, `rep.get()` returns `undefined`. Two options:

**Option A: Check and use fallbacks**

```javascript
const apiUrl = rep.get('API_URL') ?? 'http://localhost:3000';
```

**Option B: Mock payload in HTML**

```html
<script id="__rep__" type="application/json">
{
  "public": {
    "API_URL": "http://localhost:3000",
    "FEATURE_FLAGS": "dark-mode,debug"
  },
  "_meta": {
    "version": "0.1.0",
    "injected_at": "2026-01-01T00:00:00Z",
    "integrity": "hmac-sha256:dev-mode-no-verification",
    "ttl": 0
  }
}
</script>
```

## No build tool required

REP works without any build tool. If you have a static HTML site with inline `<script type="module">` tags, just import the SDK from a CDN or self-hosted path:

```html
<script type="module">
  import { rep } from '/assets/rep-sdk.esm.js';
  // Use rep.get(), rep.getSecure(), etc.
</script>
```

The gateway injects the `<script id="__rep__">` payload into your HTML regardless of how your JavaScript is loaded.

For a complete, runnable single-file app — SDK loaded from [esm.sh](https://esm.sh), no `npm install`, no build step — see the [Simple HTML example](/examples/simple-html/).


---

# Manifest File — .rep.yaml Configuration Reference

> Declare environment variables, types, defaults, and validation rules in .rep.yaml. Generate TypeScript types and validate config at gateway startup.

Source: https://rep-protocol.dev/guides/manifest/

The `.rep.yaml` manifest is optional but powerful. It enables:

- **Startup validation** — fail fast if a required variable is missing
- **Type constraints** — enforce `url`, `number`, `enum`, `csv` shapes
- **TypeScript types** — `rep typegen` generates typed `get()` / `getSecure()` overloads
- **Documentation** — a single source of truth for every variable the app uses

## Example manifest

```yaml
version: "0.1.0"

variables:
  API_URL:
    tier: public
    type: url
    required: true
    description: "Base URL for the backend REST API"
    example: "https://api.example.com"

  FEATURE_FLAGS:
    tier: public
    type: csv
    required: false
    default: ""
    description: "Comma-separated feature flags"
    example: "dark-mode,new-checkout"

  ENV_NAME:
    tier: public
    type: enum
    required: true
    values: ["development", "staging", "production"]
    description: "Current deployment environment"

  ANALYTICS_WRITE_KEY:
    tier: sensitive
    type: string
    required: true
    description: "Analytics service write key"

  OAUTH_CLIENT_ID:
    tier: sensitive
    type: string
    required: true
    pattern: "^[a-zA-Z0-9]{20,}$"
    description: "OAuth 2.0 client identifier"

  UPSTREAM_AUTH_TOKEN:
    tier: server
    type: string
    required: false
    description: "Bearer token for upstream proxying"

settings:
  strict_guardrails: true
  hot_reload: true
  session_key_ttl: "30s"
  session_key_max_rate: 10
  allowed_origins:
    - "https://app.example.com"
```

## Variable fields

| Field | Type | Required | Description |
|---|---|---|---|
| `tier` | `public` / `sensitive` / `server` | Yes | Security classification |
| `type` | see below | Yes | Value type constraint |
| `required` | boolean | No | Whether the variable must be present at startup |
| `default` | string | No | Default value if not provided |
| `description` | string | No | Human-readable description |
| `example` | string | No | Example value |
| `pattern` | string | No | Regex pattern the value must match |
| `values` | string[] | No | Allowed values (for `enum` type) |
| `deprecated` | boolean | No | Mark as deprecated |
| `deprecated_message` | string | No | Migration guidance for deprecated vars |

## Supported types

| Type | Validation |
|---|---|
| `string` | Any string value |
| `url` | Must be a valid URL |
| `number` | Must parse as a number |
| `boolean` | Must be `true`, `false`, `1`, or `0` |
| `csv` | Comma-separated values |
| `json` | Must be valid JSON |
| `enum` | Must match one of the `values` array entries |

## Settings

| Setting | Type | Default | Description |
|---|---|---|---|
| `strict_guardrails` | boolean | `false` | Exit on guardrail warnings |
| `hot_reload` | boolean | `false` | Enable hot reload SSE |
| `hot_reload_mode` | string | `signal` | `file_watch`, `signal`, or `poll` |
| `hot_reload_poll_interval` | string | `30s` | Poll interval (Go duration) |
| `session_key_ttl` | string | `30s` | Session key expiry |
| `session_key_max_rate` | number | `10` | Max session key requests per minute per IP |
| `allowed_origins` | string[] | `[]` | CORS allowed origins for session key endpoint |

## Validating

```bash
rep validate --manifest .rep.yaml
```

Output:
```
✓ Manifest is valid
  Version: 0.1.0
  Variables: 6 total
    - PUBLIC: 3
    - SENSITIVE: 2
    - SERVER: 1
  Settings configured: 4
```

Use in CI to catch configuration errors before deployment:

```yaml
- name: Validate REP manifest
  run: npx @rep-protocol/cli validate --manifest .rep.yaml
```

## Type generation

Generate TypeScript type definitions from your manifest:

```bash
rep typegen --manifest .rep.yaml --output src/rep.d.ts
```

This creates typed overloads for `get()` and `getSecure()`:

```typescript
declare module "@rep-protocol/sdk" {
  export interface REP {
    get(key: "API_URL" | "FEATURE_FLAGS" | "ENV_NAME"): string | undefined;
    getSecure(key: "ANALYTICS_WRITE_KEY" | "OAUTH_CLIENT_ID"): Promise<string>;
  }
}
```

> **Tip**
>
> Run `rep typegen` as part of your build script or as a pre-commit hook to keep types in sync with the manifest.

For the full schema reference, see [Manifest Schema Reference](/reference/manifest-schema/).


---

# Testing — Unit Tests, Integration Tests, and Bundle Scanning

> Test apps that use REP. Mock payloads for unit tests with Vitest/Jest, Docker Compose for integration tests, and rep lint for scanning built bundles for leaked secrets.

Source: https://rep-protocol.dev/guides/testing/

## Unit testing

Create a helper that mocks the REP payload for your test environment:

```typescript
// test/helpers/mock-rep.ts
export function mockRepPayload(vars: Record<string, string>) {
  // Remove any existing mock
  document.getElementById('__rep__')?.remove();

  const script = document.createElement('script');
  script.id = '__rep__';
  script.type = 'application/json';

  const payload = {
    public: vars,
    _meta: {
      version: '0.1.0',
      injected_at: new Date().toISOString(),
      integrity: 'hmac-sha256:test-mode',
      ttl: 0,
    },
  };

  script.textContent = JSON.stringify(payload);
  document.head.appendChild(script);
}
```

### Using with Vitest

```typescript
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { mockRepPayload } from '../helpers/mock-rep';

describe('Config-dependent component', () => {
  beforeEach(() => {
    // Reset module cache — SDK's _init() runs on import
    vi.resetModules();
    document.head.innerHTML = '';
    document.body.innerHTML = '';
  });

  it('reads API_URL from REP payload', async () => {
    mockRepPayload({ API_URL: 'https://api.test.com' });

    // Dynamic import gets a fresh SDK instance
    const { rep } = await import('@rep-protocol/sdk');
    expect(rep.get('API_URL')).toBe('https://api.test.com');
  });

  it('returns default when payload is absent', async () => {
    const { rep } = await import('@rep-protocol/sdk');
    expect(rep.get('API_URL', 'fallback')).toBe('fallback');
  });
});
```

> **Tip**
>
> The SDK's `_init()` function runs on module load. Use `vi.resetModules()` and dynamic `import()` in each test to get a fresh SDK instance that reads the current DOM state.

### Vitest configuration

```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',
  },
});
```

## Integration testing

Use Docker Compose to test with a real gateway:

```yaml
# docker-compose.test.yml
services:
  app:
    build: .
    environment:
      REP_PUBLIC_API_URL: "http://api:3000"
      REP_PUBLIC_FEATURE_FLAGS: "all"
      REP_SENSITIVE_ANALYTICS_KEY: "test-key"
    ports:
      - "8080:8080"

  api:
    image: your-api:test
    ports:
      - "3000:3000"
```

```bash
docker compose -f docker-compose.test.yml up -d
npx playwright test --base-url http://localhost:8080
docker compose -f docker-compose.test.yml down
```

## Health check testing

Verify the gateway is running and configured correctly:

```bash
curl -s http://localhost:8080/rep/health | jq
```

Expected output:
```json
{
  "status": "healthy",
  "version": "0.1.0",
  "variables": {
    "public": 3,
    "sensitive": 1,
    "server": 2
  },
  "guardrails": {
    "warnings": 0,
    "blocked": 0
  },
  "uptime_seconds": 42
}
```

## Bundle scanning

Use `rep lint` in CI to catch accidentally leaked secrets in build output:

```bash
rep lint --dir ./dist --strict
```

This runs the same entropy and pattern detection as the gateway guardrails, but against your compiled JavaScript bundles. Minified code patterns are automatically filtered to avoid false positives, while real secrets in bundles are still detected. Use `--exclude` to skip specific files:

```bash
rep lint --dir ./dist --strict --exclude "vendor/**,*.chunk.js"
```

Add it as a CI step to prevent deployment of bundles containing secrets. See the [CLI reference](/reference/cli/#rep-lint) for full details on minified file handling.


---

# Migration Overview — From Build-Time to Runtime Env Vars

> Four-phase migration from build-time environment variables to REP runtime injection. Covers infrastructure setup, SDK adoption, build cleanup, and security hardening.

Source: https://rep-protocol.dev/guides/migration/overview/

REP is designed for incremental adoption. You don't need to migrate everything at once — you can start with a single variable and expand from there.

## Migration phases

1. **Infrastructure**

   Set up the gateway in your deployment pipeline:
   - [ ] Download or build the gateway binary
   - [ ] Add the gateway to your Dockerfile or Kubernetes deployment
   - [ ] Configure `REP_GATEWAY_*` settings
   - [ ] Verify with `curl /rep/health`

2. **SDK adoption**

   Replace env var reads in your application code:
   - [ ] Install `@rep-protocol/sdk`
   - [ ] Replace `import.meta.env.VITE_*` / `process.env.REACT_APP_*` with `rep.get()`
   - [ ] Replace sensitive var reads with `await rep.getSecure()`
   - [ ] Add default values for local development
   - [ ] Run the codemod for automated migration (optional)

3. **Build cleanup**

   Remove build-time env var configuration:
   - [ ] Remove `.env.production`, `.env.staging` etc. from the build
   - [ ] Remove `--build-arg` flags from Docker builds
   - [ ] Remove framework-specific env var type declarations
   - [ ] Run `rep typegen` to generate SDK type declarations
   - [ ] Update CI/CD to use environment-agnostic builds

4. **Hardening**

   Enable production security features:
   - [ ] Create a `.rep.yaml` manifest with all variables declared
   - [ ] Enable `--strict` mode for guardrail enforcement
   - [ ] Configure `allowed_origins` for session key CORS
   - [ ] Add `rep validate` to CI
   - [ ] Add `rep lint` to CI to scan bundles for leaked secrets
   - [ ] Review variable classification with the [decision tree](/concepts/variable-classification/)

## Using the codemod

For automated migration, the codemod transforms env var access patterns:

```bash
# Vite projects
npx @rep-protocol/codemod --framework vite src/

# Create React App projects
npx @rep-protocol/codemod --framework cra src/

# Next.js projects
npx @rep-protocol/codemod --framework next src/
```

Use `--dry-run` to preview changes before applying:

```bash
npx @rep-protocol/codemod --framework vite --dry-run src/
```

See framework-specific migration guides:
- [From Vite](/guides/migration/from-vite/)
- [From Create React App](/guides/migration/from-cra/)
- [From Next.js](/guides/migration/from-next/)

## After migration

The codemod handles the code changes. You still need to:

1. Remove framework-specific type augmentations (e.g., `vite-env.d.ts` `ImportMeta` overrides)
2. Run `rep typegen` to generate typed SDK overloads
3. Update container config to set `REP_PUBLIC_*` / `REP_SENSITIVE_*` environment variables
4. Verify with a test deployment

> **Tip**
>
> You can start without a manifest file. The gateway works with just naming conventions. Add `.rep.yaml` later when you want validation and type generation.


---

# Migrate from Vite — Replace import.meta.env with Runtime Config

> Automated codemod to migrate from Vite's import.meta.env.VITE_* to REP runtime environment variables. Transforms all references and adds SDK imports.

Source: https://rep-protocol.dev/guides/migration/from-vite/

## Automated migration

```bash
npx @rep-protocol/codemod --framework vite src/
```

### What it transforms

```typescript
// Before
const apiUrl = import.meta.env.VITE_API_URL;
const flags = import.meta.env.VITE_FEATURE_FLAGS;

// After
import { rep } from '@rep-protocol/sdk';
const apiUrl = rep.get('API_URL');
const flags = rep.get('FEATURE_FLAGS');
```

### What it leaves alone

Vite built-in variables are **not** transformed:

- `import.meta.env.MODE`
- `import.meta.env.DEV`
- `import.meta.env.PROD`
- `import.meta.env.SSR`
- `import.meta.env.BASE_URL`

### Preview first

```bash
npx @rep-protocol/codemod --framework vite --dry-run src/
```

## Manual migration

If you prefer to migrate manually:

1. **Rename environment variables:**
   ```bash
   VITE_API_URL        → REP_PUBLIC_API_URL
   VITE_FEATURE_FLAGS  → REP_PUBLIC_FEATURE_FLAGS
   VITE_ANALYTICS_KEY  → REP_SENSITIVE_ANALYTICS_KEY
   ```

2. **Update code:**
   ```typescript
   // Before
   const apiUrl = import.meta.env.VITE_API_URL;

   // After
   import { rep } from '@rep-protocol/sdk';
   const apiUrl = rep.get('API_URL', 'http://localhost:3000');
   ```

3. **Install the SDK:**
   ```bash
   npm install @rep-protocol/sdk
   ```

## Post-migration cleanup

1. Remove `vite-env.d.ts` `ImportMeta` type augmentations (if you had custom ones)
2. Remove `.env.production` and `.env.staging` files from the project
3. Remove `envPrefix` configuration from `vite.config.ts` (if customized)
4. Run `rep typegen --manifest .rep.yaml --output src/rep.d.ts` for typed access
5. Update your Dockerfile to include the REP gateway

> **Tip**
>
> The codemod is idempotent — running it twice produces the same result. It's safe to re-run after making manual changes.


---

# Migrate from Create React App — Replace process.env.REACT_APP_*

> Automated codemod to migrate from Create React App's process.env.REACT_APP_* to REP runtime environment variables. Drop build-time env var dependency.

Source: https://rep-protocol.dev/guides/migration/from-cra/

## Automated migration

```bash
npx @rep-protocol/codemod --framework cra src/
```

### What it transforms

```typescript
// Before
const apiUrl = process.env.REACT_APP_API_URL;
const flags = process.env.REACT_APP_FEATURE_FLAGS;

// After
import { rep } from '@rep-protocol/sdk';
const apiUrl = rep.get('API_URL');
const flags = rep.get('FEATURE_FLAGS');
```

Only `REACT_APP_*` prefixed variables are transformed. Other `process.env.*` access is left unchanged.

### Preview first

```bash
npx @rep-protocol/codemod --framework cra --dry-run src/
```

## Manual migration

1. **Rename environment variables:**
   ```bash
   REACT_APP_API_URL        → REP_PUBLIC_API_URL
   REACT_APP_ANALYTICS_KEY  → REP_SENSITIVE_ANALYTICS_KEY
   ```

2. **Update code:**
   ```typescript
   import { rep } from '@rep-protocol/sdk';
   const apiUrl = rep.get('API_URL', 'http://localhost:3000');
   ```

3. **Install the SDK:**
   ```bash
   npm install @rep-protocol/sdk
   ```

## Post-migration cleanup

1. Remove `react-app-env.d.ts` (CRA's auto-generated type declarations)
2. Remove `.env.production` and `.env.staging` files
3. Run `rep typegen` for typed access
4. Update your Dockerfile to include the REP gateway


---

# Migrate from Next.js — Replace NEXT_PUBLIC_* with Runtime Config

> Migrate from Next.js NEXT_PUBLIC_* build-time variables to REP runtime environment variables. Handles client-side code, SSR considerations, and automated codemod.

Source: https://rep-protocol.dev/guides/migration/from-next/

> **Caution**
>
> REP is designed for **client-side** environment variables. Next.js server-side `process.env.*` (without `NEXT_PUBLIC_` prefix) should remain as-is — they're already server-only and don't need REP.

## Automated migration

```bash
npx @rep-protocol/codemod --framework next src/
```

### What it transforms

```typescript
// Before
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
const flags = process.env.NEXT_PUBLIC_FEATURE_FLAGS;

// After
import { rep } from '@rep-protocol/sdk';
const apiUrl = rep.get('API_URL');
const flags = rep.get('FEATURE_FLAGS');
```

Only `NEXT_PUBLIC_*` prefixed variables are transformed. Server-side `process.env.*` access is left unchanged.

### Preview first

```bash
npx @rep-protocol/codemod --framework next --dry-run src/
```

## Manual migration

1. **Rename environment variables:**
   ```bash
   NEXT_PUBLIC_API_URL        → REP_PUBLIC_API_URL
   NEXT_PUBLIC_ANALYTICS_KEY  → REP_SENSITIVE_ANALYTICS_KEY
   ```

2. **Update client-side code:**
   ```typescript
   import { rep } from '@rep-protocol/sdk';
   const apiUrl = rep.get('API_URL', 'http://localhost:3000');
   ```

3. **Install the SDK:**
   ```bash
   npm install @rep-protocol/sdk
   ```

## Post-migration cleanup

1. Remove `NEXT_PUBLIC_*` entries from `.env.local`, `.env.production`, etc.
2. Keep server-side `process.env.*` as-is (these are already server-only)
3. Run `rep typegen` for typed access
4. Update your Dockerfile to include the REP gateway

> **Note**
>
> For Next.js static export (`next export` or `output: 'export'`), REP works like any other SPA. For SSR deployments, REP handles only the client-side variables — server-side config continues to use standard Node.js `process.env`.


---

# Docker Proxy Mode — Gateway in Front of nginx or Caddy

> Deploy the REP gateway as a reverse proxy in front of nginx or Caddy. Multi-stage Dockerfile, runtime environment variable injection into HTML responses.

Source: https://rep-protocol.dev/deployment/docker-proxy/

In proxy mode, the gateway sits in front of your existing web server and injects variables into HTML responses.

```
Browser → [REP Gateway :8080] → [nginx :80]
```

## Dockerfile

```dockerfile
# Stage 1: Build the frontend
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: nginx + REP gateway
FROM nginx:alpine

# Copy built assets to nginx
COPY --from=build /app/dist /usr/share/nginx/html

# Add the REP gateway binary
COPY --from=ghcr.io/ruachtech/rep/gateway:latest \
  /usr/local/bin/rep-gateway /usr/local/bin/rep-gateway

EXPOSE 8080

ENTRYPOINT ["rep-gateway"]
CMD ["--mode", "proxy", "--upstream", "localhost:80", "--port", "8080"]
```

## Running

```bash
docker build -t myapp .

# Staging
docker run -p 8080:8080 \
  -e REP_PUBLIC_API_URL=https://api.staging.example.com \
  -e REP_PUBLIC_FEATURE_FLAGS=dark-mode,beta \
  -e REP_SENSITIVE_ANALYTICS_KEY=UA-XXXXX-staging \
  myapp

# Production — SAME IMAGE
docker run -p 8080:8080 \
  -e REP_PUBLIC_API_URL=https://api.example.com \
  -e REP_PUBLIC_FEATURE_FLAGS=dark-mode \
  -e REP_SENSITIVE_ANALYTICS_KEY=UA-XXXXX-prod \
  -e REP_GATEWAY_STRICT=true \
  myapp
```

## How it works

1. nginx starts and serves static files on port 80 (inside the container)
2. The gateway starts and proxies all requests to `localhost:80`
3. For `text/html` responses, the gateway intercepts and injects the REP payload
4. All other responses (JS, CSS, images) pass through unmodified

> **Note**
>
> The gateway strips `Accept-Encoding` from proxied requests so upstreams respond with identity encoding. This avoids decompress/recompress overhead. The gateway handles gzip compression for non-compliant upstreams via stdlib.

## When to use proxy mode

- You need nginx features (gzip, caching headers, URL rewriting, basic auth)
- You're adding REP to an existing deployment with minimal changes
- Your infrastructure team prefers nginx/Caddy for static file serving


---

# Docker Embedded Mode — Minimal FROM scratch Containers

> Deploy a frontend app in a minimal FROM scratch Docker container. The REP gateway serves static files directly — no nginx, no Node.js, no shell. Under 10MB total.

Source: https://rep-protocol.dev/deployment/docker-embedded/

In embedded mode, the gateway serves static files directly — no nginx, no Caddy, no Node.js. This produces the smallest possible production image.

## Dockerfile

```dockerfile
# Stage 1: Build the frontend
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: FROM scratch — nothing but the binary and static files
FROM scratch

COPY --from=build /app/dist /static
COPY --from=ghcr.io/ruachtech/rep/gateway:latest \
  /usr/local/bin/rep-gateway /rep-gateway

EXPOSE 8080
USER 65534:65534

ENTRYPOINT ["/rep-gateway"]
CMD ["--mode", "embedded", "--static-dir", "/static", "--port", "8080", "--strict"]
```

## What's in the image

Exactly two things:
- Your built static files (`dist/`)
- The REP gateway binary (~7MB)

No OS, no shell, no utilities, no package manager. Attack surface: near zero.

## Running

```bash
docker build -t myapp .

docker run -p 8080:8080 \
  -e REP_PUBLIC_API_URL=https://api.example.com \
  -e REP_SENSITIVE_ANALYTICS_KEY=UA-XXXXX \
  -e REP_GATEWAY_STRICT=true \
  -e REP_GATEWAY_ALLOWED_ORIGINS=https://app.example.com \
  myapp
```

## Multi-architecture builds

```dockerfile
# In the gateway download stage
ARG TARGETARCH
# The gateway image is multi-arch — Docker selects the correct binary
COPY --from=ghcr.io/ruachtech/rep/gateway:latest \
  /usr/local/bin/rep-gateway /rep-gateway
```

## Security hardening

The `FROM scratch` + non-root pattern provides:

- **No shell** — `docker exec` attacks are impossible
- **No package manager** — no malware installation vector
- **Read-only filesystem** — compatible with `readOnlyRootFilesystem: true`
- **Non-root user** — UID 65534 (`nobody`)
- **Static binary** — no shared libraries, no dynamic linker

> **Tip**
>
> Embedded mode is recommended for production deployments where you don't need nginx-specific features. The gateway handles HTTP/2, compression, and caching headers natively.

## When to use embedded mode

- You want the smallest possible container image
- You're deploying a pure SPA with no server-side rendering
- Security is a priority (minimal attack surface)
- You don't need nginx-specific features (URL rewriting, basic auth, etc.)


---

# Kubernetes Deployment — ConfigMaps, Secrets, and Hot Reload

> Deploy REP in Kubernetes with ConfigMaps for public vars, Secrets for sensitive vars, sidecar patterns, and hot reload via file watch. Includes health probes and Service config.

Source: https://rep-protocol.dev/deployment/kubernetes/

## Embedded deployment

The simplest Kubernetes deployment — gateway serves files directly:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
        - name: app
          image: myapp:latest
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef:
                name: frontend-public-config
            - secretRef:
                name: frontend-sensitive-config
          livenessProbe:
            httpGet:
              path: /rep/health
              port: 8080
            initialDelaySeconds: 5
          readinessProbe:
            httpGet:
              path: /rep/health
              port: 8080
            initialDelaySeconds: 2

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: frontend-public-config
data:
  REP_PUBLIC_API_URL: "https://api.example.com"
  REP_PUBLIC_FEATURE_FLAGS: "dark-mode"
  REP_PUBLIC_ENV_NAME: "production"
  REP_GATEWAY_STRICT: "true"

---
apiVersion: v1
kind: Secret
metadata:
  name: frontend-sensitive-config
type: Opaque
stringData:
  REP_SENSITIVE_ANALYTICS_KEY: "UA-XXXXX-prod"
  REP_SENSITIVE_SENTRY_DSN: "https://abc@sentry.io/123"
```

## Sidecar pattern (with nginx)

When you want nginx serving files with the gateway as a sidecar:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  template:
    spec:
      containers:
        - name: nginx
          image: nginx:alpine
          volumeMounts:
            - name: static-files
              mountPath: /usr/share/nginx/html
              readOnly: true
          ports:
            - containerPort: 80

        - name: rep-gateway
          image: ghcr.io/ruachtech/rep/gateway:latest
          args:
            - "--upstream=localhost:80"
            - "--port=8080"
            - "--strict"
            - "--env-file=/config/.env"
            - "--hot-reload"
            - "--hot-reload-mode=file_watch"
            - "--watch-path=/config"
          volumeMounts:
            - name: config-volume
              mountPath: /config
              readOnly: true
          ports:
            - containerPort: 8080
          livenessProbe:
            httpGet:
              path: /rep/health
              port: 8080

      initContainers:
        - name: copy-static
          image: myapp:latest
          command: ['cp', '-r', '/app/dist/.', '/static/']
          volumeMounts:
            - name: static-files
              mountPath: /static

      volumes:
        - name: static-files
          emptyDir: {}
        - name: config-volume
          configMap:
            name: frontend-dynamic-config
```

The mounted ConfigMap must hold a single key containing a whole `.env` file, because `--env-file` reads one env-format file:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: frontend-dynamic-config
data:
  .env: |
    REP_PUBLIC_API_URL=https://api.example.com
    REP_PUBLIC_FEATURE_FLAGS=dark-mode
    REP_PUBLIC_ENV_NAME=production
```

## Hot reload with ConfigMaps

Use file watch mode to detect ConfigMap changes without pod restarts:

1. Mount the ConfigMap as a volume, with a single key holding a whole `.env` file
2. Point the gateway at it with `--env-file=/config/.env` — this is what reload re-reads
3. Enable `--hot-reload --hot-reload-mode=file_watch --watch-path=/config`
4. Update the ConfigMap: `kubectl apply -f configmap.yaml`
5. Kubernetes swaps the volume's `..data` symlink, changing the mount directory's mtime
6. The gateway detects the change, re-reads the env file, and broadcasts via SSE
7. Connected browsers receive the update

> **Do not also set these variables via envFrom**
>
> Reload merges the env file first, then lets the process environment overwrite it. A variable supplied through both `envFrom` and `--env-file` keeps its `envFrom` value permanently — `envFrom` is captured once at container start, so the reload succeeds but the injected value never changes. Use `envFrom` only for variables you are content to change with a pod restart, and never for a key that also appears in the env file.

Variables passed through `envFrom` alone are **not** hot-reloadable. Changing `frontend-public-config` or `frontend-sensitive-config` above requires a pod restart (`kubectl rollout restart`). To rotate a `REP_SENSITIVE_*` value without one, move it into the mounted env file — sourced from a Secret instead of a ConfigMap — since `--env-file` accepts a single path.

```bash
# Update a config value
kubectl patch configmap frontend-dynamic-config \
  -p '{"data":{"REP_PUBLIC_FEATURE_FLAGS":"dark-mode,ai-assist"}}'
```

> **Tip**
>
> Use `--health-port 9090` to serve health checks on a separate port. This keeps the health endpoint accessible only within the cluster while the main port faces the load balancer.

## Service

```yaml
apiVersion: v1
kind: Service
metadata:
  name: frontend
spec:
  selector:
    app: frontend
  ports:
    - port: 80
      targetPort: 8080
  type: ClusterIP
```


---

# Docker Compose — Same Image, Different Config Per Environment

> Run the same frontend Docker image across staging and production with Docker Compose. Different environment variables per service, .env file support, and dev proxy setup.

Source: https://rep-protocol.dev/deployment/docker-compose/

## Basic setup

```yaml
# docker-compose.yml
services:
  frontend:
    build: .
    ports:
      - "8080:8080"
    environment:
      REP_PUBLIC_API_URL: "http://localhost:3000"
      REP_PUBLIC_FEATURE_FLAGS: "dark-mode,debug"
      REP_SENSITIVE_ANALYTICS_KEY: "test-key"
```

## Same image, multiple environments

The core value proposition — one image, different config per environment:

```yaml
services:
  frontend-staging:
    image: myapp:latest
    ports:
      - "8080:8080"
    environment:
      REP_PUBLIC_API_URL: "https://api.staging.example.com"
      REP_PUBLIC_FEATURE_FLAGS: "dark-mode,beta-checkout"
      REP_PUBLIC_ENV_NAME: "staging"
      REP_SENSITIVE_ANALYTICS_KEY: "UA-XXXXX-staging"
      REP_SERVER_INTERNAL_SECRET: "staging-secret"

  frontend-prod:
    image: myapp:latest  # SAME IMAGE
    ports:
      - "8081:8080"
    environment:
      REP_PUBLIC_API_URL: "https://api.example.com"
      REP_PUBLIC_FEATURE_FLAGS: "dark-mode"
      REP_PUBLIC_ENV_NAME: "production"
      REP_SENSITIVE_ANALYTICS_KEY: "UA-XXXXX-prod"
      REP_SERVER_INTERNAL_SECRET: "prod-secret"
      REP_GATEWAY_STRICT: "true"
```

## With .env files

```yaml
services:
  frontend:
    build: .
    ports:
      - "8080:8080"
    env_file:
      - .env.local
```

`.env.local`:
```bash
REP_PUBLIC_API_URL=http://localhost:3000
REP_PUBLIC_FEATURE_FLAGS=dark-mode,debug
REP_SENSITIVE_ANALYTICS_KEY=test-key-123
```

## Development with proxy mode

Run the gateway as a proxy to your Vite dev server:

```yaml
services:
  vite:
    build:
      context: .
      target: dev
    command: npm run dev -- --host
    ports:
      - "5173:5173"
    volumes:
      - .:/app
      - /app/node_modules

  gateway:
    image: ghcr.io/ruachtech/rep/gateway:latest
    ports:
      - "8080:8080"
    environment:
      REP_PUBLIC_API_URL: "http://localhost:3000"
      REP_GATEWAY_MODE: "proxy"
      REP_GATEWAY_UPSTREAM: "vite:5173"
      REP_GATEWAY_HOT_RELOAD: "true"
    depends_on:
      - vite
```

Access the app at `http://localhost:8080` to see REP-injected variables.

## Full stack example

```yaml
services:
  frontend:
    build: .
    ports:
      - "8080:8080"
    environment:
      REP_PUBLIC_API_URL: "http://localhost:3000"
      REP_PUBLIC_FEATURE_FLAGS: "all"
      REP_SENSITIVE_ANALYTICS_KEY: "test-key"
    depends_on:
      - api

  api:
    image: your-api:latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: "postgres://user:pass@db:5432/app"
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: app
```


---

# CI/CD Pipeline — Build Once, Deploy Everywhere

> Build your frontend Docker image once in CI and promote it across staging and production without rebuilding. GitHub Actions example with manifest validation and bundle scanning.

Source: https://rep-protocol.dev/deployment/ci-cd/

## The fundamental shift

With REP, your CI/CD pipeline changes from "build per environment" to "build once, promote everywhere":

**Before REP:**
```
Build (staging) → Test → Deploy to staging
Build (prod)    → Deploy to prod  ← DIFFERENT BINARY
```

**After REP:**
```
Build (once) → Test → Deploy to staging (with staging env vars)
                    → Promote SAME IMAGE to prod (with prod env vars)
```

The image that passed your tests is the **exact same binary** that goes to production.

## GitHub Actions example

```yaml
name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build frontend (environment-agnostic)
        run: |
          docker build -t myapp:${{ github.sha }} .
          # No --build-arg for API_URL, no .env files
          # The image is environment-agnostic

      - name: Push to registry
        run: docker push ghcr.io/myorg/myapp:${{ github.sha }}

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Run E2E tests
        run: |
          docker run -d --name test-app \
            -e REP_PUBLIC_API_URL=https://api.test.example.com \
            -e REP_PUBLIC_FEATURE_FLAGS=all \
            -p 8080:8080 \
            ghcr.io/myorg/myapp:${{ github.sha }}

          npx playwright test --base-url http://localhost:8080

  deploy-staging:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to staging
        run: |
          kubectl set image deployment/frontend \
            frontend=ghcr.io/myorg/myapp:${{ github.sha }}
          # ConfigMap provides staging REP_PUBLIC_* and REP_SENSITIVE_* vars

  deploy-prod:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production  # Requires manual approval
    steps:
      - name: Promote SAME IMAGE to production
        run: |
          # SAME SHA — exact same binary that was tested
          kubectl set image deployment/frontend \
            frontend=ghcr.io/myorg/myapp:${{ github.sha }}
          # Different ConfigMap provides prod REP_* vars
```

## Manifest validation in CI

Add a validation step to catch configuration errors early:

```yaml
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate REP manifest
        run: npx @rep-protocol/cli validate --manifest .rep.yaml
```

This checks that:
- The manifest schema is valid
- No naming collisions after prefix stripping
- All type constraints are properly declared

## Bundle scanning in CI

Scan built bundles for accidentally leaked secrets:

```yaml
  lint:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build
      - name: Scan for secrets
        run: npx @rep-protocol/cli lint --dir ./dist --strict
```

Minified code patterns are automatically filtered to avoid false positives, while real secrets in bundles are still detected. Use `--exclude` to skip specific files:

```yaml
      - name: Scan for secrets
        run: npx @rep-protocol/cli lint --dir ./dist --strict --exclude "vendor/**"
```

> **Tip**
>
> Combine `rep validate` and `rep lint` as required CI checks. Validation catches schema issues at commit time; lint catches leaked secrets at build time.


---

# Todo App Example — React with Runtime Environment Variables

> Full worked example of a React todo app using REP. useRep() hooks, useRepSecure() for encrypted vars, hot reload, and Docker deployment with FROM scratch containers.

Source: https://rep-protocol.dev/examples/todo-react/

A complete React todo app demonstrating all REP features. Source code at [`examples/todo-react/`](https://github.com/ruachtech/rep/tree/main/examples/todo-react).

## Features demonstrated

| Feature | Component/File | REP API |
|---|---|---|
| Public variable access | `App.tsx` | `useRep('APP_TITLE')` |
| Enum validation | `Header.tsx` | `useRep('ENV_NAME')` |
| URL variable | `TodoList.tsx` | `useRep('API_URL')` |
| Number constraint | `TodoList.tsx` | `useRep('MAX_TODOS')` |
| Sensitive variable | `Analytics.tsx` | `useRepSecure('ANALYTICS_KEY')` |
| Payload metadata | `Footer.tsx` | `rep.meta()` |

## Environment variables

| Variable | Tier | Type | Default | Description |
|---|---|---|---|---|
| `APP_TITLE` | public | string | `"Todo App"` | Page title |
| `ENV_NAME` | public | enum | — | `development`, `staging`, `production` |
| `API_URL` | public | url | — | Backend API endpoint |
| `MAX_TODOS` | public | number | `100` | Maximum todo items |
| `ANALYTICS_KEY` | sensitive | string | — | Analytics tracking key |

## Running locally

### With the Vite plugin (recommended)

The project includes `@rep-protocol/vite` in `vite.config.ts`. No gateway needed for development:

```bash
cd examples/todo-react
pnpm install
pnpm dev
```

Open `http://localhost:5173`. The Vite plugin reads `.env.local` and injects the REP payload automatically.

### With the CLI gateway

If you need full gateway fidelity (rate-limited session keys, CORS origin checking):

```bash
# Terminal 1: Start Vite dev server
pnpm dev

# Terminal 2: Start REP gateway proxy
pnpm dev:gateway
```

Open `http://localhost:3000` (the gateway port).

### With Docker

```bash
cd examples/todo-react
docker build -t rep-todo .

# Run with staging config
docker run -p 8080:8080 \
  -e REP_PUBLIC_APP_TITLE="Todo - Staging" \
  -e REP_PUBLIC_ENV_NAME=staging \
  -e REP_PUBLIC_API_URL=https://api.staging.example.com \
  -e REP_PUBLIC_MAX_TODOS=50 \
  -e REP_SENSITIVE_ANALYTICS_KEY=UA-XXXXX-staging \
  rep-todo

# Same image, production config
docker run -p 8080:8080 \
  -e REP_PUBLIC_APP_TITLE="Todo" \
  -e REP_PUBLIC_ENV_NAME=production \
  -e REP_PUBLIC_API_URL=https://api.example.com \
  -e REP_SENSITIVE_ANALYTICS_KEY=UA-XXXXX-prod \
  rep-todo
```

## Hot reload

With the CLI dev server running, edit `.env.local` and send SIGHUP to the gateway:

```bash
# Edit .env.local, then:
kill -HUP $(pidof rep-gateway)
```

Components using `useRep()` re-render automatically.

## Dockerfile

The example uses a 3-stage multi-stage build:

1. **Download gateway:** Alpine + curl fetches the pre-built binary from GitHub Releases
2. **Build app:** Node + pnpm builds SDK, React adapter, and the app in dependency order
3. **Final image:** `FROM scratch` with just the gateway binary and static files

> **Tip**
>
> The `FROM scratch` final image contains no OS, no shell, and no package manager. Total size is approximately 8MB (6MB gateway + 2MB static assets).


---

# Simple HTML — No Build Step

> Use REP in a plain HTML file with no bundler or framework. The SDK is loaded via esm.sh and the gateway serves the file in embedded mode with a FROM scratch container.

Source: https://rep-protocol.dev/examples/simple-html/

A single HTML file using the REP SDK via [esm.sh](https://esm.sh), served by the gateway in embedded mode. No build step, no bundler, no framework.

Source code at [`examples/simple-html/`](https://github.com/ruachtech/rep/tree/main/examples/simple-html).

## When to use this pattern

- Static marketing pages or single-file dashboards
- Quick prototyping without a build pipeline
- Demonstrating REP concepts with minimal infrastructure
- Environments where adding a Node.js build step is impractical

## File structure

- examples/simple-html/
  - index.html  Single HTML file — the entire app
  - Dockerfile  Two-stage: gateway download → FROM scratch
  - .rep.yaml   Optional manifest for validate/typegen
  - .env.example Template environment variables

## How it works

The REP gateway runs in **embedded mode**, serving `index.html` directly. When a browser requests the page, the gateway injects the `__rep__` payload before the response is sent:

```
Browser → REP Gateway :8080 (embedded mode)
          ↓ injects <script id="__rep__" type="application/json">…</script>
          ↓ serves index.html
```

The HTML file imports the SDK as an ES module from esm.sh — no npm install, no bundler:

```html
<script type="module">
  import { rep } from 'https://esm.sh/@rep-protocol/sdk@0.1.8';

  // Public vars — synchronous, available immediately
  const apiUrl  = rep.get('API_URL', 'http://localhost:3001');
  const envName = rep.get('ENV_NAME', 'development');

  // Sensitive var — AES-256-GCM encrypted, decrypted on demand
  const analyticsKey = await rep.getSecure('ANALYTICS_KEY');

  // Hot reload — react to config changes pushed via SSE
  rep.onChange('FEATURE_FLAGS', (next) => {
    document.getElementById('features').textContent = next || '(none)';
  });
</script>
```

> **Tip**
>
> The `__rep__` script tag is injected **before** the browser parses `<script type="module">`, so `rep.get()` is synchronous and always returns a value — no loading state needed.

## Dockerfile

A two-stage build. No app build step is needed — the HTML file is copied as-is:

```dockerfile
FROM alpine:3.21 AS gateway
ARG GATEWAY_VERSION=0.1.3
RUN apk add --no-cache curl ca-certificates && \
    curl -fsSL "…/rep-gateway_${GATEWAY_VERSION}_linux_amd64.tar.gz" \
      -o /tmp/gateway.tar.gz && \
    tar -xzf /tmp/gateway.tar.gz -C /tmp && \
    mv /tmp/rep-gateway /rep-gateway && \
    chmod +x /rep-gateway

FROM scratch
COPY --from=gateway /rep-gateway /rep-gateway
COPY index.html /static/index.html
COPY --from=gateway /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
USER 65534:65534
EXPOSE 8080
ENTRYPOINT ["/rep-gateway", "--mode", "embedded", "--static-dir", "/static"]
```

The final image contains: gateway binary + one HTML file + CA certificates. Total size is approximately 6MB.

## Running locally

### Docker

```bash
cd examples/simple-html

docker build -t rep-simple-html .

docker run --rm -p 8080:8080 \
  -e REP_PUBLIC_APP_TITLE="My App" \
  -e REP_PUBLIC_API_URL=https://api.example.com \
  -e REP_PUBLIC_ENV_NAME=production \
  -e REP_PUBLIC_FEATURE_FLAGS=dark-mode,beta \
  -e REP_SENSITIVE_ANALYTICS_KEY=ak_live_abc123 \
  rep-simple-html
```

### Without Docker (CLI)

```bash
cd examples/simple-html

# Serve the HTML file locally with the gateway
npx @rep-protocol/cli dev \
  --mode embedded \
  --static-dir . \
  --env-file .env.local
```

## Changing config

No rebuild required. Stop, change env vars, restart:

```bash
# Production config
docker run --rm -p 8080:8080 \
  -e REP_PUBLIC_API_URL=https://api.prod.example.com \
  -e REP_PUBLIC_FEATURE_FLAGS=dark-mode \
  rep-simple-html

# Staging config — same image
docker run --rm -p 8080:8080 \
  -e REP_PUBLIC_API_URL=https://api.staging.example.com \
  -e REP_PUBLIC_FEATURE_FLAGS=dark-mode,beta,new-checkout \
  rep-simple-html
```

Same `index.html`. Same Docker image. Different runtime config.

## Security note

The esm.sh `import` call happens in the browser after the page loads. For production, consider pinning the SDK version and adding an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) or hosting the SDK on your own CDN to remove the esm.sh dependency. If you self-host the SDK and load it via `<script type="module" src="...">`, you can add an `integrity` attribute for [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) verification. Note that SRI works on `<script src>` / `<link>` tags, not on bare `import` statements inside a module.


---

# Next.js — Proxy Mode

> Run the REP gateway as a reverse proxy in front of a Next.js SSR server. Environment variables are injected into every HTML response without touching the Next.js build.

Source: https://rep-protocol.dev/examples/nextjs-proxy/

The REP gateway runs in **proxy mode** in front of a Next.js server. It intercepts every HTML response and injects the `__rep__` payload — no changes to the Next.js build pipeline required.

Source code at [`examples/nextjs-proxy/`](https://github.com/ruachtech/rep/tree/main/examples/nextjs-proxy).

## Architecture

```
Client → REP Gateway :8080 (proxy mode)
              ↓ injects __rep__ payload into HTML responses
         Next.js Server :3000
```

The Next.js server is never exposed directly. All traffic flows through the gateway. Config lives entirely in the gateway's environment variables — the Next.js image is the same across every deployment.

## When to use this pattern

- Next.js App Router or Pages Router with server-side rendering (SSR)
- You want the full Next.js server (streaming, server actions, API routes)
- Docker Compose, Kubernetes single-container pod, or multi-service deployments

## File structure

- examples/nextjs-proxy/
  - src/
    - app/
      - layout.tsx         Includes RepScript for dev-time injection
      - page.tsx           Server component shell
      - api/rep/session-key/
        - route.ts         Dev-only session key endpoint
    - components/
      - EnvDisplay.tsx     Client component — reads REP vars
      - IntegrityBanner.tsx  Verifies payload was not modified in transit
  - Dockerfile             Next.js-only image (for docker-compose)
  - Dockerfile.single      Gateway + Next.js in one image (for Kubernetes)
  - docker-compose.yml     Two-service stack (recommended)
  - docker-entrypoint.sh   Startup script for Dockerfile.single
  - next.config.ts
  - .rep.yaml
  - .env.example

## Reading REP vars in Next.js

REP runs entirely in the browser. In the App Router, use `'use client'` components:

```tsx
'use client';

import { useRep, useRepSecure } from '@rep-protocol/react';

export function EnvDisplay() {
  // Synchronous — available on first render, no loading state
  const apiUrl   = useRep('API_URL',  'http://localhost:3001');
  const envName  = useRep('ENV_NAME', 'development');
  const features = useRep('FEATURE_FLAGS', '');

  // Async — decrypted via the session-key endpoint
  const { value: analyticsKey, loading } = useRepSecure('ANALYTICS_KEY');

  return (
    <div>
      <p>Environment: {envName}</p>
      <p>API: {apiUrl}</p>
      <p>Key: {loading ? 'loading…' : analyticsKey}</p>
    </div>
  );
}
```

> **Caution**
>
> Do NOT call `rep.get()` in server components — the `__rep__` payload exists only in the browser DOM. REP vars are always accessed from `'use client'` components.

## Integrity verification

The example includes an `IntegrityBanner` client component that verifies the payload was not modified after the gateway injected it. The SDK checks a SHA-256 SRI hash embedded on the `<script id="__rep__">` tag using the Web Crypto API. A mismatch means something (a CDN, a misconfigured proxy) altered the payload in transit.

```tsx
'use client';

import { useEffect, useState } from 'react';
import { rep } from '@rep-protocol/sdk';

export function IntegrityBanner() {
  const [ok, setOk] = useState<boolean | null>(null);

  useEffect(() => {
    // _verifySRI fires as a microtask during SDK init — await a tick first
    Promise.resolve().then(() => setOk(rep.verify()));
  }, []);

  if (ok === null)  return <p>Verifying payload integrity…</p>;
  if (ok)           return <p>✅ Payload integrity verified</p>;
  return <p>🚨 Integrity check FAILED — payload may have been tampered with</p>;
}
```

## Deployment options

**Docker Compose (two services)**

Recommended for development and multi-service production setups. Gateway and Next.js run as separate containers:

```yaml
services:
  gateway:
    image: ghcr.io/ruachtech/rep/gateway:0.1.3
    ports:
      - "8080:8080"
    environment:
      REP_GATEWAY_MODE: proxy
      REP_GATEWAY_UPSTREAM: "app:3000"
      REP_PUBLIC_API_URL: "https://api.example.com"
      REP_PUBLIC_ENV_NAME: "production"
      REP_PUBLIC_FEATURE_FLAGS: "dark-mode"
      REP_SENSITIVE_ANALYTICS_KEY: "ak_live_abc123"
    depends_on:
      - app

  app:
    build: .
    expose:
      - "3000"
    environment:
      NODE_ENV: production
    # No REP_PUBLIC_* vars here — gateway injects them at request time
```

```bash
cd examples/nextjs-proxy
docker compose up
```

To change config without rebuilding:

```bash
# Edit REP_PUBLIC_* in docker-compose.yml, then:
docker compose up -d gateway   # restart only the gateway
```

**Single container (Kubernetes)**

`Dockerfile.single` packages the gateway and Next.js server into one image. A startup script (`docker-entrypoint.sh`) launches both processes:

```sh
#!/bin/sh
# Start Next.js in the background
NODE_ENV=production node /app/server.js &

# REP gateway in the foreground (proxy → localhost:3000)
exec rep-gateway --mode proxy --port 8080 --upstream localhost:3000
```

Build and run:

```bash
docker build -f Dockerfile.single -t rep-nextjs-proxy .

docker run --rm -p 8080:8080 \
  -e REP_PUBLIC_API_URL=https://api.example.com \
  -e REP_PUBLIC_ENV_NAME=production \
  -e REP_PUBLIC_FEATURE_FLAGS=dark-mode \
  -e REP_SENSITIVE_ANALYTICS_KEY=ak_live_abc123 \
  rep-nextjs-proxy
```

**Kubernetes** — pass config from a ConfigMap + Secret:

```yaml
containers:
  - name: frontend
    image: your-registry/rep-nextjs-proxy:latest
    ports:
      - containerPort: 8080
    envFrom:
      - configMapRef:
          name: rep-config      # REP_PUBLIC_* and REP_GATEWAY_*
      - secretRef:
          name: rep-secrets     # REP_SENSITIVE_*
```

See [`examples/nextjs-csr-embedded/k8s/`](https://github.com/ruachtech/rep/tree/main/examples/nextjs-csr-embedded/k8s) for complete Kubernetes manifests including Service and Ingress.

## Local development

### With `@rep-protocol/next` (recommended)

The project includes `RepScript` in `app/layout.tsx` and a session-key route handler. No gateway needed for development:

```bash
cp .env.example .env.local   # if you haven't already
npm run dev
```

Open `http://localhost:3000`. `RepScript` injects the REP payload during `next dev` and returns `null` in production.

### With the CLI gateway

If you need full gateway fidelity:

```bash
# Terminal 1 — run Next.js dev server
npm run dev   # starts on :3000

# Terminal 2 — run REP gateway in proxy mode
npx @rep-protocol/cli dev --proxy http://localhost:3000 --env .env.local
```

Open `http://localhost:8080`.


---

# Next.js CSR — Embedded Mode + Kubernetes

> Export Next.js as a static site, serve it with the REP gateway in embedded mode, and manage feature flags dynamically via a Kubernetes ConfigMap. Includes a hot-reload variant with zero pod restarts.

Source: https://rep-protocol.dev/examples/nextjs-csr-embedded/

Next.js with `output: 'export'` produces a fully static site. The REP gateway serves the output in **embedded mode** — no Node.js server needed in production. A Kubernetes ConfigMap holds all runtime config. Update it to change feature flags across all pods without rebuilding the image.

Source code at [`examples/nextjs-csr-embedded/`](https://github.com/ruachtech/rep/tree/main/examples/nextjs-csr-embedded).

## Architecture

```
Browser → REP Gateway :8080 (embedded mode)
          │ serves /static (Next.js export)
          │ injects __rep__ payload from environment vars
          └ environment vars come from Kubernetes ConfigMap + Secret
```

No upstream server. No Node.js runtime in production. The final container is `FROM scratch`.

## When to use this pattern

- Next.js app with no server-side rendering requirements (pure CSR)
- Kubernetes deployments where you want to change feature flags without rebuilds
- Minimal container surface area (`FROM scratch`, ~8MB total image size)

## File structure

- examples/nextjs-csr-embedded/
  - src/
    - app/
      - layout.tsx
      - page.tsx
    - components/
      - ConfigPanel.tsx  Reads REP public + sensitive vars
      - FeatureFlags.tsx  Hot-reload-aware flag toggle display
  - k8s/
    - configmap.yaml          Standard envFrom pattern
    - configmap-envfile.yaml  Hot-reload variant (mounted as file)
    - deployment.yaml         Both variants documented
    - secret.yaml             Sensitive vars
    - service.yaml + Ingress
  - Dockerfile  3-stage: gateway + Next.js build + FROM scratch
  - next.config.ts  output: 'export'
  - .rep.yaml
  - .env.example

## Next.js static export

Set `output: 'export'` in `next.config.ts`:

```typescript
const nextConfig: NextConfig = {
  output: 'export',
  images: { unoptimized: true },  // required for static export
};
```

The build produces an `out/` directory of static HTML/CSS/JS. This is what the gateway serves.

## Reading REP vars in client components

```tsx
'use client';

import { useRep, useRepSecure } from '@rep-protocol/react';

export function ConfigPanel() {
  // Synchronous — available on first render
  const apiUrl  = useRep('API_URL',  'http://localhost:3001');
  const envName = useRep('ENV_NAME', 'development');

  // Decrypted on demand (async)
  const { value: analyticsKey, loading } = useRepSecure('ANALYTICS_KEY');

  return (/* … */);
}
```

```tsx
'use client';

import { useRep } from '@rep-protocol/react';

export function FeatureFlags() {
  // useRep() subscribes to hot reload — component re-renders
  // when FEATURE_FLAGS changes without a page refresh
  const rawFlags = useRep('FEATURE_FLAGS', '');
  const active   = new Set(rawFlags.split(',').map(f => f.trim()).filter(Boolean));

  return (
    <ul>
      {['dark-mode', 'new-checkout', 'ai-assist'].map(flag => (
        <li key={flag}>{active.has(flag) ? '✅' : '⬜'} {flag}</li>
      ))}
    </ul>
  );
}
```

## Dockerfile (FROM scratch)

Three stages: download gateway, build Next.js, assemble scratch image:

```dockerfile
FROM alpine:3.21 AS gateway
ARG GATEWAY_VERSION=0.1.3
RUN apk add --no-cache curl ca-certificates && \
    curl -fsSL "…/rep-gateway_${GATEWAY_VERSION}_linux_amd64.tar.gz" \
      | tar -xz -C /tmp && \
    mv /tmp/rep-gateway /rep-gateway && chmod +x /rep-gateway

FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci
COPY . .
RUN npm run build   # produces out/

FROM scratch
COPY --from=gateway /rep-gateway /rep-gateway
COPY --from=builder /app/out /static
COPY --from=gateway /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
USER 65534:65534
EXPOSE 8080
ENTRYPOINT ["/rep-gateway", "--mode", "embedded", "--static-dir", "/static"]
```

## Kubernetes: ConfigMap for feature flags

### Standard pattern (envFrom)

Store all `REP_PUBLIC_*` vars in a ConfigMap. Sensitive vars go in a Secret:

```yaml
# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: rep-config
data:
  REP_PUBLIC_API_URL: "https://api.example.com"
  REP_PUBLIC_ENV_NAME: "production"
  REP_PUBLIC_FEATURE_FLAGS: "dark-mode,new-checkout"   # ← update this to toggle flags
  REP_GATEWAY_MODE: "embedded"
  REP_GATEWAY_HOT_RELOAD: "true"
```

```yaml
# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: rep-secrets
stringData:
  REP_SENSITIVE_ANALYTICS_KEY: "ak_live_replace_me"
```

Reference both in the Deployment:

```yaml
envFrom:
  - configMapRef:
      name: rep-config
  - secretRef:
      name: rep-secrets
```

To update feature flags:

```bash
kubectl edit configmap rep-config
# Change REP_PUBLIC_FEATURE_FLAGS, save

kubectl rollout restart deployment/frontend
# New pods start with updated config
```

### Hot-reload variant (zero pod restarts)

Mount the ConfigMap as a `.env` file and start the gateway with `--hot-reload --hot-reload-mode=file_watch`:

1. **Apply the env-file ConfigMap**

   ```bash
   kubectl apply -f k8s/configmap-envfile.yaml
   ```

   The ConfigMap stores a `.env` file as a single key:

   ```yaml
   data:
     rep.env: |
       REP_PUBLIC_API_URL=https://api.example.com
       REP_PUBLIC_FEATURE_FLAGS=dark-mode,new-checkout
   ```

2. **Mount the file in the Deployment**

   ```yaml
   args:
     - "--mode=embedded"
     - "--static-dir=/static"
     - "--env-file=/config/rep.env"
     - "--hot-reload"
     - "--hot-reload-mode=file_watch"
     - "--watch-path=/config/rep.env"
   volumeMounts:
     - name: rep-config-volume
       mountPath: /config
       readOnly: true
   volumes:
     - name: rep-config-volume
       configMap:
         name: rep-config-envfile
   ```

3. **Update feature flags**

   ```bash
   kubectl edit configmap rep-config-envfile
   # Change REP_PUBLIC_FEATURE_FLAGS in the rep.env block, save
   ```

4. **Wait ~60 seconds**

   Kubernetes propagates ConfigMap changes to mounted files. The gateway detects the file change, re-reads vars, re-encrypts sensitive values with a fresh ephemeral key, and pushes a reload event to all connected browsers via `/rep/changes` (SSE).

5. **Components re-render automatically**

   Any component using `useRep('FEATURE_FLAGS')` re-renders with the new value. No pod restart, no page refresh.

> **Note**
>
> The hot-reload file-watch variant requires the gateway to be started with `--env-file` and `--watch-path` flags pointing to the mounted ConfigMap file. Sensitive vars still come from the `secretRef` (not the mounted file) since Secrets should not be mounted as env files.

## Running locally

### Docker

```bash
cd examples/nextjs-csr-embedded

docker build -t rep-nextjs-csr .

docker run --rm -p 8080:8080 \
  -e REP_PUBLIC_API_URL=https://api.example.com \
  -e REP_PUBLIC_ENV_NAME=production \
  -e REP_PUBLIC_FEATURE_FLAGS=dark-mode,new-checkout \
  -e REP_SENSITIVE_ANALYTICS_KEY=ak_live_abc123 \
  rep-nextjs-csr
```

### CLI dev mode

```bash
cd examples/nextjs-csr-embedded

# Build the static export
npm run build   # → out/

# Serve with gateway in embedded mode
npx @rep-protocol/cli dev \
  --mode embedded \
  --static-dir ./out \
  --env-file .env.local
```

## Comparison: static vs SSR

| | CSR + Embedded (this example) | SSR + Proxy |
|---|---|---|
| Next.js `output` | `'export'` (static) | default (server) |
| Runtime container | `FROM scratch` (~8MB) | Node.js image (~150MB) |
| Server features | ❌ No API routes, no SSR | ✅ Full Next.js server |
| Feature flag updates | ConfigMap edit + SIGHUP (no restart) | ConfigMap edit + rolling restart |
| Gateway mode | `embedded` | `proxy` |

Use the CSR + embedded pattern when you don't need server-side rendering or Next.js API routes. Use the [proxy mode example](/examples/nextjs-proxy/) when you do.


---

# SDK API Reference — get(), getSecure(), onChange()

> Complete API reference for @rep-protocol/sdk. Synchronous get() for public vars, async getSecure() for encrypted vars, onChange() for hot reload, verify() for integrity checks.

Source: https://rep-protocol.dev/reference/sdk/

`@rep-protocol/sdk` — Zero-dependency, framework-agnostic TypeScript SDK for reading REP-injected environment variables.

```bash
npm install @rep-protocol/sdk
```

## `get(key)`

Retrieve a PUBLIC tier variable. Synchronous — no network call, no promise.

```typescript
function get(key: string): string | undefined;
function get(key: string, defaultValue: string): string;
```

| Parameter | Type | Description |
|---|---|---|
| `key` | `string` | Variable name (after prefix stripping, e.g. `'API_URL'`) |
| `defaultValue` | `string` | Optional fallback if the variable is not present |

**Returns:** The variable value, `defaultValue`, or `undefined`.

```typescript
import { rep } from '@rep-protocol/sdk';

const apiUrl = rep.get('API_URL');                    // string | undefined
const apiUrl = rep.get('API_URL', 'http://localhost'); // string (never undefined)
```

## `getSecure(key)`

Retrieve a SENSITIVE tier variable. Fetches a session key, decrypts the blob, and caches all sensitive values.

```typescript
function getSecure(key: string): Promise<string>;
```

| Parameter | Type | Description |
|---|---|---|
| `key` | `string` | Variable name (e.g. `'ANALYTICS_KEY'`) |

**Returns:** `Promise<string>` — the decrypted value.

**Throws:** `REPError` in the following cases:
- The requested key does not exist in the sensitive payload
- The session key endpoint is unreachable or returns a non-2xx status
- The session key has expired (30s TTL)
- Decryption fails (corrupted payload or mismatched key)

Always wrap `getSecure()` in a try/catch:

```typescript
import { rep, REPError } from '@rep-protocol/sdk';

try {
  const analyticsKey = await rep.getSecure('ANALYTICS_KEY');
} catch (err) {
  if (err instanceof REPError) {
    // Key not found, endpoint unreachable, or decryption failed.
    console.error(err.message);
  }
}
```

> **Note**
>
> The first `getSecure()` call fetches a session key and decrypts **all** sensitive variables at once. Subsequent calls for different keys return from the in-memory cache without network requests.

## `getAll()`

Retrieve all PUBLIC tier variables as a frozen object.

```typescript
function getAll(): Readonly<Record<string, string>>;
```

**Returns:** A frozen `Record<string, string>` of all public variables. Empty object if no payload is present.

```typescript
const allVars = rep.getAll();
console.log(allVars.API_URL);
```

## `verify()`

Check whether the REP payload is present and its integrity is valid.

```typescript
function verify(): boolean;
```

**Returns:** `true` if the payload is present, parseable, and the SRI hash matches. `false` if missing, malformed, or tampered.

```typescript
if (!rep.verify()) {
  console.error('REP payload missing or tampered');
}
```

## `meta()`

Returns metadata about the current REP payload.

```typescript
function meta(): REPMeta | null;

interface REPMeta {
  version: string;
  injectedAt: Date;
  integrityValid: boolean;
  publicCount: number;
  sensitiveAvailable: boolean;
  hotReloadAvailable: boolean;
}
```

**Returns:** `REPMeta` object, or `null` if no payload is present.

```typescript
const m = rep.meta();
if (m) {
  console.log('REP version:', m.version);
  console.log('Injected at:', m.injectedAt);
  console.log('Public vars:', m.publicCount);
}
```

## `onChange(key, callback)`

Register a callback for when a specific variable changes via hot reload.

```typescript
function onChange(
  key: string,
  callback: (newValue: string, oldValue: string | undefined) => void
): () => void;
```

**Returns:** An unsubscribe function. Call it to stop listening.

The SSE connection is established lazily on the first `onChange()` or `onAnyChange()` call. It is closed when all listeners have been removed.

```typescript
const unsub = rep.onChange('FEATURE_FLAGS', (newValue, oldValue) => {
  console.log(`Changed: ${oldValue} → ${newValue}`);
});

// Later:
unsub();
```

## `onAnyChange(callback)`

Register a callback for any variable change.

```typescript
function onAnyChange(
  callback: (key: string, newValue: string, oldValue: string | undefined) => void
): () => void;
```

**Returns:** An unsubscribe function.

```typescript
const unsub = rep.onAnyChange((key, newValue) => {
  console.log(`${key} updated to ${newValue}`);
});
```

## `REPError`

Custom error class thrown by SDK operations.

```typescript
class REPError extends Error {
  name: 'REPError';
}
```

Thrown by `getSecure()` when the session key endpoint is unreachable, the key has expired, or decryption fails.

## Import styles

Both named exports and a namespace object are available:

```typescript
// Named imports
import { get, getSecure, verify, onChange } from '@rep-protocol/sdk';

// Namespace import (recommended)
import { rep } from '@rep-protocol/sdk';
rep.get('API_URL');
```

## Initialization behavior

On import, the SDK synchronously:

1. Locates `<script id="__rep__">` in the DOM
2. Parses the JSON content
3. Triggers async SRI verification (non-blocking)
4. Freezes the `public` object
5. Sets `_available` and `_tampered` internal flags

No network calls are made during initialization.


---

# Gateway Flags and Environment Variables

> All CLI flags and REP_GATEWAY_* environment variables for configuring the gateway. Port, mode, upstream, strict mode, hot reload, logging, CORS, and rate limiting options.

Source: https://rep-protocol.dev/reference/gateway-flags/

The gateway is configured via command-line flags or environment variables. Flags take precedence over env vars.

## Command-line flags

```
rep-gateway [flags]
```

| Flag | Default | Description |
|---|---|---|
| `--mode` | `proxy` | Operating mode: `proxy` or `embedded` |
| `--upstream` | `localhost:80` | Upstream server address (proxy mode only) |
| `--port` | `8080` | Listen port |
| `--static-dir` | `/usr/share/nginx/html` | Static file directory (embedded mode only) |
| `--manifest` | — | Path to `.rep.yaml` manifest file |
| `--env-file` | — | Path to `.env` file (env vars take precedence) |
| `--strict` | `false` | Exit on guardrail warnings |
| `--hot-reload` | `false` | Enable hot reload SSE endpoint |
| `--hot-reload-mode` | `signal` | Detection mode: `file_watch`, `signal`, `poll` |
| `--watch-path` | — | Path to watch for changes (file_watch mode) |
| `--poll-interval` | `30s` | Config poll interval (poll mode) |
| `--log-format` | `json` | Log format: `json` or `text` |
| `--log-level` | `info` | Log level: `debug`, `info`, `warn`, `error` |
| `--allowed-origins` | — | Comma-separated CORS origins for `/rep/session-key` |
| `--tls-cert` | — | Path to TLS certificate |
| `--tls-key` | — | Path to TLS private key |
| `--health-port` | — | Separate port for health check endpoint |

## Environment variables

Every flag can be set via environment variable with the `REP_GATEWAY_` prefix:

```bash
REP_GATEWAY_MODE=proxy
REP_GATEWAY_UPSTREAM=localhost:80
REP_GATEWAY_PORT=8080
REP_GATEWAY_STRICT=true
REP_GATEWAY_HOT_RELOAD=true
REP_GATEWAY_HOT_RELOAD_MODE=signal
REP_GATEWAY_LOG_FORMAT=json
REP_GATEWAY_LOG_LEVEL=info
REP_GATEWAY_ALLOWED_ORIGINS=https://app.example.com,https://staging.example.com
```

## Precedence order

1. Command-line flags (highest)
2. Environment variables (`REP_GATEWAY_*`)
3. Manifest file settings (lowest)

## Common configurations

### Proxy mode (development)

```bash
rep-gateway \
  --mode proxy \
  --upstream localhost:5173 \
  --port 8080 \
  --hot-reload
```

### Embedded mode (production)

```bash
rep-gateway \
  --mode embedded \
  --static-dir /static \
  --port 8080 \
  --strict \
  --log-format json \
  --allowed-origins https://app.example.com
```

### Kubernetes sidecar

```bash
rep-gateway \
  --mode proxy \
  --upstream localhost:80 \
  --port 8080 \
  --strict \
  --hot-reload \
  --hot-reload-mode file_watch \
  --watch-path /config \
  --health-port 9090
```


---

# Gateway Endpoints — Health, Session Key, and SSE Changes

> REP gateway HTTP endpoints. /rep/health for status checks, /rep/session-key for AES decryption keys with rate limiting, and /rep/changes for SSE hot reload events.

Source: https://rep-protocol.dev/reference/gateway-endpoints/

## `GET /rep/health`

Returns gateway health status including variable counts and guardrail status.

**Response:**
```json
{
  "status": "healthy",
  "version": "0.1.0",
  "variables": {
    "public": 3,
    "sensitive": 1,
    "server": 2
  },
  "guardrails": {
    "warnings": 0,
    "blocked": 0
  },
  "uptime_seconds": 3421
}
```

**Use cases:**
- Kubernetes liveness/readiness probes
- Load balancer health checks
- Monitoring dashboards

**Kubernetes probe example:**
```yaml
livenessProbe:
  httpGet:
    path: /rep/health
    port: 8080
  initialDelaySeconds: 5
readinessProbe:
  httpGet:
    path: /rep/health
    port: 8080
  initialDelaySeconds: 2
```

Use `--health-port` to serve the health endpoint on a separate port (e.g., `9090`) to keep it internal to the cluster.

## `GET /rep/session-key`

Issues a short-lived decryption key for SENSITIVE tier variables. Called by the SDK's `getSecure()` method.

**Request requirements:**
- Must include an `Origin` header matching configured allowed origins (if origins are configured)
- If no allowed origins are configured, same-origin requests are permitted

**Response:**
```json
{
  "key": "{base64_encoded_derived_aes_key}",
  "expires_at": "2026-02-18T14:30:30.000Z"
}
```

| Field | Description |
|---|---|
| `key` | HKDF-derived AES-256 encryption key, base64-encoded |
| `expires_at` | RFC 3339 timestamp — key expires 30 seconds after issuance |

**Security constraints:**
- Keys expire within 30 seconds
- Rate-limited to 10 requests per minute per client IP
- Not cacheable (`Cache-Control: no-store, no-cache, must-revalidate`)
- CORS restricted to configured origins
- All issuances are audit-logged (`rep.session_key.issued`)

**Error responses:**
- `429 Too Many Requests` — rate limit exceeded
- `403 Forbidden` — origin not allowed
- `404 Not Found` — no SENSITIVE variables configured

> **Caution**
>
> The session key is the derived key, not the master key material. Even if intercepted, it cannot be used to derive the master key or generate new session keys.

## `GET /rep/changes`

Server-Sent Events (SSE) stream that pushes configuration updates to connected clients. Only available when `--hot-reload` is enabled.

**Event format:**

```
event: rep:config:update
data: {"key": "FEATURE_FLAGS", "tier": "public", "value": "dark-mode,ai-assist"}
id: 1708267830000

event: rep:config:delete
data: {"key": "DEPRECATED_FLAG", "tier": "public"}
id: 1708267831000
```

**Event types:**

| Event | Description |
|---|---|
| `rep:config:update` | A variable's value changed or a new variable was added |
| `rep:config:delete` | A variable was removed |

**Behavior:**
- SSE has built-in reconnection — the browser automatically reconnects on disconnect
- The `id` field allows replay of missed events
- Returns `404 Not Found` if hot reload is not enabled
- Only PUBLIC tier changes are broadcast (SENSITIVE changes require a page reload)


---

# Manifest Schema — .rep.yaml File Format Reference

> Complete reference for the .rep.yaml manifest. Variable declarations, supported types (string, url, number, boolean, csv, json, enum), defaults, required flags, and gateway settings.

Source: https://rep-protocol.dev/reference/manifest-schema/

The manifest schema is published as JSON Schema at [`/schema/rep-manifest.schema.json`](/schema/rep-manifest.schema.json).

## Top-level fields

```yaml
version: "0.1.0"      # Required — protocol version
variables: { ... }     # Required — variable declarations
settings: { ... }      # Optional — gateway settings
```

## Variable declaration

Each variable is declared under the `variables` map using its **stripped** name (e.g., `API_URL`, not `REP_PUBLIC_API_URL`):

```yaml
variables:
  API_URL:
    tier: public        # Required: public, sensitive, or server
    type: url           # Required: string, url, number, boolean, csv, json, enum
    required: true      # Optional (default: false)
    default: ""         # Optional — default value if not provided
    description: "..."  # Optional — human-readable description
    example: "..."      # Optional — example value
    pattern: "^..."     # Optional — regex pattern the value must match
    values: [...]       # Optional — allowed values (enum type only)
    deprecated: false   # Optional — mark as deprecated
    deprecated_message: "Use NEW_VAR instead"  # Optional
```

### Field reference

| Field | Type | Required | Description |
|---|---|---|---|
| `tier` | `public` \| `sensitive` \| `server` | Yes | Security classification tier |
| `type` | see types table | Yes | Value type constraint |
| `required` | `boolean` | No | Must be present at startup (default: `false`) |
| `default` | `string` | No | Default value when variable is absent |
| `description` | `string` | No | Human-readable purpose |
| `example` | `string` | No | Example value for documentation |
| `pattern` | `string` | No | Regex the value must match |
| `values` | `string[]` | No | Allowed values (for `enum` type) |
| `deprecated` | `boolean` | No | Mark as deprecated |
| `deprecated_message` | `string` | No | Migration guidance |

### Supported types

| Type | Validation | Example |
|---|---|---|
| `string` | Any string | `"hello"` |
| `url` | Valid URL (RFC 3986) | `"https://api.example.com"` |
| `number` | Parses as finite number | `"42"`, `"3.14"` |
| `boolean` | `"true"`, `"false"`, `"1"`, `"0"` | `"true"` |
| `csv` | Comma-separated string | `"a,b,c"` |
| `json` | Valid JSON | `'{"key":"val"}'` |
| `enum` | Matches `values` array | `"production"` |

## Settings

```yaml
settings:
  strict_guardrails: true
  hot_reload: true
  hot_reload_mode: "signal"
  hot_reload_poll_interval: "30s"
  session_key_ttl: "30s"
  session_key_max_rate: 10
  allowed_origins:
    - "https://app.example.com"
```

| Setting | Type | Default | Description |
|---|---|---|---|
| `strict_guardrails` | `boolean` | `false` | Fail on guardrail warnings |
| `hot_reload` | `boolean` | `false` | Enable hot reload SSE |
| `hot_reload_mode` | `string` | `signal` | `file_watch`, `signal`, or `poll` |
| `hot_reload_poll_interval` | `string` | `30s` | Poll interval (Go duration format) |
| `session_key_ttl` | `string` | `30s` | Session key expiry duration |
| `session_key_max_rate` | `integer` | `10` | Max session key requests/min/IP |
| `allowed_origins` | `string[]` | `[]` | CORS origins for session key endpoint |

## Full example

See [`examples/.rep.yaml`](https://github.com/ruachtech/rep/blob/main/examples/.rep.yaml) for an annotated manifest with all tiers and types.


---

# CLI Commands — validate, typegen, lint, dev

> Reference for @rep-protocol/cli commands. Validate manifests, generate TypeScript types from .rep.yaml, scan bundles for leaked secrets, and run a local dev server.

Source: https://rep-protocol.dev/reference/cli/

```bash
npm install -g @rep-protocol/cli
# or
npx @rep-protocol/cli [command]
```

## `rep validate`

Validate a `.rep.yaml` manifest against the JSON schema.

```bash
rep validate [--manifest <path>]
```

| Flag | Default | Description |
|---|---|---|
| `-m, --manifest <path>` | `.rep.yaml` | Path to manifest file |

**Example:**
```bash
$ rep validate --manifest .rep.yaml
✓ Manifest is valid
  Version: 0.1.0
  Variables: 11 total
    - PUBLIC: 6
    - SENSITIVE: 3
    - SERVER: 2
  Settings configured: 6
```

## `rep typegen`

Generate TypeScript type definitions from a manifest. Creates strongly-typed overloads for `rep.get()` and `rep.getSecure()`.

```bash
rep typegen [--manifest <path>] [--output <path>]
```

| Flag | Default | Description |
|---|---|---|
| `-m, --manifest <path>` | `.rep.yaml` | Path to manifest file |
| `-o, --output <path>` | `src/rep.d.ts` | Output path for generated types |

**Generated output:**
```typescript
declare module "@rep-protocol/sdk" {
  export interface REP {
    // Overloaded: passing a defaultValue narrows the return type to string.
    get(key: "API_URL" | "FEATURE_FLAGS", defaultValue: string): string;
    get(key: "API_URL" | "FEATURE_FLAGS", defaultValue?: undefined): string | undefined;
    getSecure(key: "ANALYTICS_KEY"): Promise<string>;
    // ... other methods
  }
  export function get(key: "API_URL" | "FEATURE_FLAGS", defaultValue: string): string;
  export function get(key: "API_URL" | "FEATURE_FLAGS", defaultValue?: undefined): string | undefined;
  export function getSecure(key: "ANALYTICS_KEY"): Promise<string>;
  // ...
}
```

**Strict by design** — the key unions are closed. Calling `rep.get('UNDECLARED_KEY')` is a TypeScript error if that variable is not declared in `.rep.yaml`. This is intentional: it forces every variable the app reads to be explicitly declared in the manifest, keeping the manifest the single source of truth. The fix is always to add the missing variable to `.rep.yaml` and re-run `rep typegen`, not to widen the types.

If you don't want strict type enforcement, skip `rep typegen` and rely on the base SDK types (`key: string`).

## `rep lint`

Scan built JavaScript bundles for accidentally leaked secrets. Uses the same guardrail detection as the gateway (Shannon entropy, known secret formats).

```bash
rep lint [--dir <path>] [--pattern <glob>] [--exclude <patterns>] [--strict]
```

| Flag | Default | Description |
|---|---|---|
| `-d, --dir <path>` | `./dist` | Directory to scan |
| `--pattern <glob>` | `**/*.{js,mjs,cjs}` | File pattern to scan |
| `--exclude <patterns>` | — | Comma-separated glob patterns to exclude (e.g., `"*.min.js,vendor/**"`) |
| `--strict` | `false` | Exit with error code if warnings found |

### Minified code handling

The linter filters out false positives from minified/bundled code while still detecting real secrets embedded in your bundles.

**File-level skip:** Files with `.min.js` / `.min.mjs` / `.min.cjs` extensions are skipped entirely, as these are typically third-party vendor bundles. If your build pipeline produces application code with `.min.js` filenames, rename the output or run `rep lint` against the non-minified build.

**String-level filtering:** For all other files (including Vite, webpack, and Rollup bundles), extracted string values are checked for JavaScript language constructs (`function`, `return`, `if`, `=>`, `===`, `&&`, `.method()`, `key:value`, etc.) and skipped if they look like compiled code. This means real secrets accidentally embedded in a bundle are still detected, while minified code noise is filtered out.

If you still get false positives, use `--exclude` to skip specific files or directories.

**Example:**
```bash
$ rep lint --dir ./dist
⚠ dist/main.js
  high_entropy:42: value has high entropy (5.23 bits/char) — may be a secret
    const key = "sk_live_abc123..."

⚠ Found 1 potential secret(s) in 1 file(s)
```

```bash
# Exclude vendor bundles
$ rep lint --dir ./dist --exclude "vendor/**,*.chunk.js"
```

**Use cases:**
- CI/CD pipeline step before deployment
- Pre-commit hook
- Regular audits of production bundles

## `rep dev`

Run a local development server with the REP gateway. Loads env vars from a file and starts the gateway.

```bash
rep dev [options]
```

| Flag | Default | Description |
|---|---|---|
| `-e, --env <path>` | `.env.local` | Path to .env file |
| `-p, --port <number>` | `8080` | Gateway port |
| `--proxy <url>` | — | Upstream proxy URL (e.g., `http://localhost:5173`) |
| `--static <path>` | — | Serve static files (embedded mode) |
| `--hot-reload` | `false` | Enable hot reload |
| `--gateway-bin <path>` | auto | Path to gateway binary |

**Example workflows:**

```bash
# Proxy mode with Vite
rep dev --env .env.local --proxy http://localhost:5173

# Embedded mode with static files
rep dev --env .env.local --static ./dist --port 8080
```

## Binary resolution

The CLI looks for the gateway binary in this order:

1. Bundled binary (downloaded during `npm install`)
2. Custom path via `--gateway-bin`
3. `rep-gateway` in system `PATH`


---

# React Adapter API — useRep() and useRepSecure() Hooks

> API reference for @rep-protocol/react. useRep() for synchronous public variable access with hot reload re-rendering. useRepSecure() for encrypted variable decryption.

Source: https://rep-protocol.dev/reference/adapters/react/

```bash
npm install @rep-protocol/react @rep-protocol/sdk
```

## `useRep(key, defaultValue?)`

```typescript
function useRep(key: string): string | undefined;
function useRep(key: string, defaultValue: string): string;
```

Reads a PUBLIC tier variable. Synchronous, hot-reload-aware.

| Parameter | Type | Description |
|---|---|---|
| `key` | `string` | Variable name (e.g., `'API_URL'`) |
| `defaultValue` | `string` | Optional fallback value |

**Returns:** `string | undefined` (or `string` if `defaultValue` provided).

**Behavior:**
- Reads from the injected payload immediately (no loading state)
- Subscribes to hot reload in `useEffect`
- Unsubscribes on unmount
- Re-renders component when the variable changes

## `useRepSecure(key)`

```typescript
function useRepSecure(key: string): {
  value: string | null;
  loading: boolean;
  error: Error | null;
};
```

Reads a SENSITIVE tier variable. Async — fetches a session key on first call.

| Parameter | Type | Description |
|---|---|---|
| `key` | `string` | Variable name (e.g., `'ANALYTICS_KEY'`) |

**Returns:** `{ value, loading, error }` state object.

**Behavior:**
- Initial state: `{ value: null, loading: true, error: null }`
- Success: `{ value: '...', loading: false, error: null }`
- Failure: `{ value: null, loading: false, error: Error }`
- Decrypted value is cached for the page lifetime
- Re-fetches if `key` changes
- Cleans up on unmount (cancelled flag prevents state update after unmount)

## Requirements

- React >= 16.8
- `@rep-protocol/sdk` peer dependency


---

# Vue Adapter API — useRep() and useRepSecure() Composables

> API reference for @rep-protocol/vue. useRep() returns a reactive Ref for public variables. useRepSecure() returns an async Ref for encrypted variable decryption.

Source: https://rep-protocol.dev/reference/adapters/vue/

```bash
npm install @rep-protocol/vue @rep-protocol/sdk
```

## `useRep(key, defaultValue?)`

```typescript
function useRep(key: string, defaultValue?: string): Ref<string | undefined>;
```

Reads a PUBLIC tier variable as a reactive `Ref`.

| Parameter | Type | Description |
|---|---|---|
| `key` | `string` | Variable name |
| `defaultValue` | `string` | Optional fallback value |

**Returns:** `Ref<string | undefined>`

**Behavior:**
- Set immediately from the injected payload
- Subscribes to hot reload on creation
- Unsubscribes via `onUnmounted`
- Must be called inside `setup()`

## `useRepSecure(key)`

```typescript
function useRepSecure(key: string): Ref<string | null>;
```

Reads a SENSITIVE tier variable as a reactive `Ref`.

| Parameter | Type | Description |
|---|---|---|
| `key` | `string` | Variable name |

**Returns:** `Ref<string | null>`

**Behavior:**
- Starts as `null`
- Resolves after session key fetch and decryption
- Errors are swallowed (SDK logs them); ref stays `null`
- Does **not** subscribe to hot reload

## Requirements

- Vue >= 3.0
- `@rep-protocol/sdk` peer dependency
- Must be called from `setup()` for `onUnmounted` cleanup


---

# Svelte Adapter API — repStore() and repSecureStore()

> API reference for @rep-protocol/svelte. repStore() creates a readable store for public variables with SSE hot reload. repSecureStore() for async encrypted variable access.

Source: https://rep-protocol.dev/reference/adapters/svelte/

```bash
npm install @rep-protocol/svelte @rep-protocol/sdk
```

## `repStore(key, defaultValue?)`

```typescript
function repStore(key: string, defaultValue?: string): Readable<string | undefined>;
```

Reads a PUBLIC tier variable as a Svelte `Readable` store.

| Parameter | Type | Description |
|---|---|---|
| `key` | `string` | Variable name |
| `defaultValue` | `string` | Optional fallback value |

**Returns:** `Readable<string | undefined>`

**Behavior:**
- Synchronous initial value from the payload
- SSE subscription is **lazy** — established only when the store has subscribers
- Updates automatically on config changes via hot reload
- SSE connection closes when all subscribers unsubscribe

## `repSecureStore(key)`

```typescript
function repSecureStore(key: string): Readable<string | null>;
```

Reads a SENSITIVE tier variable as a `Readable` store.

| Parameter | Type | Description |
|---|---|---|
| `key` | `string` | Variable name |

**Returns:** `Readable<string | null>`

**Behavior:**
- Starts as `null`
- Resolves after session key fetch and decryption
- Errors are swallowed (SDK logs them); store stays `null`
- Does **not** support hot reload

## Requirements

- Svelte >= 4 or Svelte 5
- `@rep-protocol/sdk` peer dependency


---

# Vite Plugin Reference — @rep-protocol/vite

> API reference for the REP Vite plugin. repPlugin() options, dev-mode behavior, the /rep/session-key middleware, and how it differs from the production gateway.

Source: https://rep-protocol.dev/reference/plugins/vite/

```bash
npm install -D @rep-protocol/vite
```

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { repPlugin } from '@rep-protocol/vite';

export default defineConfig({
  plugins: [repPlugin()],
});
```

## `repPlugin(options?)`

```typescript
interface RepPluginOptions {
  env?: string;
  strict?: boolean;
}

function repPlugin(options?: RepPluginOptions): Plugin;
```

| Option | Type | Default | Description |
|---|---|---|---|
| `env` | `string` | `'.env.local'` | Path to the env file, relative to the project root. Classified the same way as the gateway: `REP_PUBLIC_*`, `REP_SENSITIVE_*`, `REP_SERVER_*` prefixes. |
| `strict` | `boolean` | `false` | Turn guardrail warnings into thrown errors instead of console warnings. |

```ts
repPlugin({
  env: '.env.development',
  strict: true,
})
```

## Behavior

- **Dev only.** The plugin only runs during `vite dev` (`configureServer` hook). It does nothing during `vite build` — production HTML ships with no `__rep__` script tag, and the gateway injects it at serve time instead.
- **Injects `<script id="__rep__">`** into every HTML response via `transformIndexHtml`, using the same JSON shape, HMAC integrity token, and SRI hash format as the Go gateway. `rep.get()`, `rep.getSecure()`, and `rep.verify()` behave identically whether the payload came from the plugin or the gateway.
- **Watches the env file.** Changes to the file at `env` trigger a full page reload (`server.ws.send({ type: 'full-reload' })`) — no restart needed.
- **Serves `GET /rep/session-key`** as dev middleware, so `rep.getSecure()` works without a separate gateway process. Unlike the gateway's endpoint, this dev version has no rate limiting or single-use enforcement — it's not meant to run in production.
- **Runs guardrails** (entropy + known secret-format scanning) on every `REP_PUBLIC_*` value at each rebuild, logging warnings through the Vite server logger.
- **Ephemeral keys per dev-server start.** A fresh AES key and HMAC secret are generated when the dev server boots and again on every env-file change — matching the gateway's "new keys on every restart" behavior.

> **Caution**
>
> The plugin produces byte-identical payload JSON to the gateway (sorted keys, Go-style `&lt;&gt;&amp;` escaping), but it is a development convenience, not a production component. Don't run `vite preview` with an unstripped `.env.local` and call it deployed — the gateway is the only thing that should inject config in production.

## See also

- [Local Development guide](/guides/development/) — where this fits alongside the CLI dev server and mock-payload approaches
- [React framework guide](/frameworks/react/) — using the plugin with `useRep()` / `useRepSecure()`
- [Next.js plugin reference](/reference/plugins/next/) — the equivalent for Next.js


---

# Next.js Plugin Reference — @rep-protocol/next

> API reference for the REP Next.js plugin. RepScript props, the session-key route handler, and how the plugin behaves in dev vs. production builds.

Source: https://rep-protocol.dev/reference/plugins/next/

```bash
npm install -D @rep-protocol/next
```

```tsx
// app/layout.tsx
import type { ReactNode } from 'react';
import { RepScript } from '@rep-protocol/next';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html>
      <head><RepScript /></head>
      <body>{children}</body>
    </html>
  );
}
```

## `<RepScript />`

```typescript
interface RepScriptProps {
  env?: string;
  strict?: boolean;
}

function RepScript(props?: RepScriptProps): React.ReactElement | null;
```

A React Server Component. Renders `<script id="__rep__">` during `next dev`; renders `null` in production.

| Prop | Type | Default | Description |
|---|---|---|---|
| `env` | `string` | `'.env.local'` | Path to the env file, resolved relative to `process.cwd()`. Same `REP_PUBLIC_*` / `REP_SENSITIVE_*` / `REP_SERVER_*` classification as the gateway. |
| `strict` | `boolean` | `false` | Turn guardrail warnings into thrown errors instead of `console.warn`. |

```tsx
<RepScript env=".env.development" strict />
```

## `GET` — session-key route handler

```ts
// app/api/rep/session-key/route.ts
export { GET } from '@rep-protocol/next/session-key';
```

Only needed if you read `REP_SENSITIVE_*` variables with `rep.getSecure()` / `useRepSecure()` during development. Returns the ephemeral AES key as JSON, matching the gateway's `/rep/session-key` response shape.

> **Caution**
>
> **Returns 404 in production** (`NODE_ENV === 'production'`). This dev handler has no rate limiting, no single-use token enforcement, and no CORS origin checking — the gateway's `/rep/session-key` endpoint is the only one hardened for production use. Don't route around the 404 by hand-rolling your own version of this handler.

## Behavior

- **Renders nothing in production.** `NODE_ENV === 'production'` (which `next build` sets automatically) makes `RepScript` return `null`. This also prevents build-time env vars from being baked into the static output — the whole point of REP is that config is resolved after the build, not during it.
- **Server Component only.** `RepScript` reads the filesystem (`env`) and generates keys server-side; it cannot be used in a Client Component. Consume the injected payload from Client Components via `rep.get()` / `useRep()` as usual — the SDK reads the DOM, not React context.
- **Script content is Go-escaped** (`<`, `>`, `&` → `<`, `>`, `&`) before being written via `dangerouslySetInnerHTML`, preventing `</script>` breakout from untrusted env values. The tag still carries `type="application/json"`, so the browser never executes it.
- **Ephemeral keys are process-scoped**, held in a module-level singleton (`getOrCreateKeys()`) so the same key survives across route handler invocations within one `next dev` process.
- **Byte-identical payload** to the Go gateway and the Vite plugin (sorted keys, same HMAC + SRI format) — `rep.verify()` and `rep.meta()` behave the same regardless of which one produced the payload.

## App Router only

`RepScript` is a Server Component and requires the App Router (`app/`). The Pages Router (`pages/`) doesn't support React Server Components — use the [CLI dev server](/guides/development/#option-d-cli-dev-server-full-fidelity) or [mock payload](/guides/development/#option-c-mock-payload-in-html) approach instead.

## See also

- [Local Development guide](/guides/development/) — where this fits alongside the CLI dev server and mock-payload approaches
- [Next.js — Proxy Mode example](/examples/nextjs-proxy/) — production deployment behind the gateway
- [Vite plugin reference](/reference/plugins/vite/) — the equivalent for Vite


---

# Codemod Reference — Automated Migration Tool

> Automated codemod to migrate from Vite import.meta.env, CRA process.env.REACT_APP_*, and Next.js NEXT_PUBLIC_* to REP runtime environment variables. Idempotent and non-destructive.

Source: https://rep-protocol.dev/reference/codemod/

```bash
npm install -D @rep-protocol/codemod
# or
npx @rep-protocol/codemod [options] [files...]
```

## Usage

```bash
rep-codemod [options] [files or directories...]
```

## Options

| Flag | Default | Description |
|---|---|---|
| `-f, --framework <name>` | `vite` | Framework preset: `vite`, `cra`, `next` |
| `--dry-run` | `false` | Preview changes without writing files |
| `--extensions <list>` | `ts,tsx,js,jsx` | Comma-separated file extensions to process |

## Framework presets

### `--framework vite`

Transforms `import.meta.env.VITE_*` to `rep.get('*')`:

```typescript
// Before
const apiUrl = import.meta.env.VITE_API_URL;

// After
import { rep } from '@rep-protocol/sdk';
const apiUrl = rep.get('API_URL');
```

Vite built-ins (`MODE`, `DEV`, `PROD`, `SSR`, `BASE_URL`) are left untouched.

### `--framework cra`

Transforms `process.env.REACT_APP_*` to `rep.get('*')`:

```typescript
// Before
const apiUrl = process.env.REACT_APP_API_URL;

// After
import { rep } from '@rep-protocol/sdk';
const apiUrl = rep.get('API_URL');
```

### `--framework next`

Transforms `process.env.NEXT_PUBLIC_*` to `rep.get('*')`:

```typescript
// Before
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// After
import { rep } from '@rep-protocol/sdk';
const apiUrl = rep.get('API_URL');
```

## Examples

```bash
# Transform Vite project
rep-codemod --framework vite src/

# Dry run — preview changes
rep-codemod --framework cra --dry-run src/components/

# Specific files
rep-codemod --framework next src/app/page.tsx src/lib/api.ts

# JavaScript files only
rep-codemod --framework vite --extensions js,jsx src/
```

## Behavior

- **Idempotent** — running twice produces the same result
- **Import management** — adds `import { rep } from '@rep-protocol/sdk'` if absent
- **Non-destructive** — only prefixed variables are transformed
- **Format-preserving** — original formatting and comments are preserved (via jscodeshift/recast)

## Post-migration steps

1. Remove framework-specific type augmentations (e.g., `vite-env.d.ts`)
2. Run `rep typegen` to generate typed overloads
3. Update container config to set `REP_PUBLIC_*` environment variables


---

# Specification Overview — REP Protocol Documents

> Formal specification documents for the Runtime Environment Protocol. RFC-0001 core protocol, security model threat analysis, and conformance requirements for implementations.

Source: https://rep-protocol.dev/spec/

REP is defined by three specification documents. They are the authoritative reference for the protocol, its security properties, and its conformance requirements.

## Documents

| Document | Status | Version | Description |
|---|---|---|---|
| [REP-RFC-0001](/spec/rfc-0001/) | Active | 0.1.0 | Core protocol specification — variable classification, gateway architecture, SDK API, wire format, deployment patterns |
| [Security Model](/spec/security-model/) | Active | 0.1.0 | Threat model, 7 threat analyses, hardening recommendations, known limitations |
| [Conformance](/spec/conformance/) | Active | 0.1.0 | Requirements for conformant gateway and SDK implementations |

## Versioning policy

The specification uses semantic versioning:

- **Patch** (0.1.x): Clarifications, typo fixes, non-normative additions
- **Minor** (0.x.0): New optional features, backwards-compatible extensions
- **Major** (x.0.0): Breaking changes to the wire format, API surface, or security model

The current version (0.1.0) indicates the specification is active and subject to refinement based on implementation experience. Breaking changes are possible before 1.0.

## License

Specification documents are licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Reference implementations (gateway, SDK, CLI, adapters) are licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).

## JSON schemas

Machine-readable schemas are published for integration and validation:

- [Payload schema](/schema/rep-payload.schema.json) — validates the injected `<script>` JSON
- [Manifest schema](/schema/rep-manifest.schema.json) — validates `.rep.yaml` files

## References

- [The Twelve-Factor App — Factor III: Config](https://12factor.net/config)
- [OCI Image Specification](https://github.com/opencontainers/image-spec)
- [RFC 5869 — HKDF](https://tools.ietf.org/html/rfc5869)
- [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)
- [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)
- [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html)
- [Content Security Policy Level 3](https://www.w3.org/TR/CSP3/)


---

# REP-RFC-0001 — Core Protocol Specification

> The core protocol specification for the Runtime Environment Protocol v0.1.0. Variable classification, gateway behaviour, SDK API, wire format, encryption, and deployment patterns.

Source: https://rep-protocol.dev/spec/rfc-0001/

```
Title:    Runtime Environment Protocol (REP)
Version:  0.1.0
Status:   Active
Authors:  Olamide Adebayo (Ruach Tech)
Created:  2026-02-18
License:  CC BY 4.0
```

> **Note**
>
> This is the formal specification. For a practical introduction, see [How REP Works](/concepts/how-it-works/) and the [Quick Start](/quick-start/).

## Abstract

This document specifies the **Runtime Environment Protocol (REP)**, a standardised method for injecting environment variables into browser-hosted applications at container startup rather than at build time. REP introduces a three-tier security classification system, cryptographic integrity verification, and an optional hot-reload mechanism.

REP operates at the infrastructure layer. It requires no build-tool plugins, no framework-specific adapters, and no changes to the application's build process.

## Sections

The full specification covers 14 sections. Key topics are documented separately in the docs site:

- [Variable Classification](/concepts/variable-classification/) — §3 — Three-tier system, classification rules, guardrails
- [How REP Works](/concepts/how-it-works/) — §4 — Gateway architecture, startup sequence, HTML injection
- [SDK API Reference](/reference/sdk/) — §5 — Core API, initialization behavior, type generation
- [Manifest File](/guides/manifest/) — §6 — .rep.yaml schema, supported types, settings
- [Gateway Flags](/reference/gateway-flags/) — §7 — CLI flags and environment variable configuration
- [Wire Format](/concepts/wire-format/) — §8 — Payload JSON, encrypted blob, HMAC integrity
- [Deployment Patterns](/deployment/docker-embedded/) — §9 — Docker, Kubernetes, sidecar patterns
- [Migration](/guides/migration/overview/) — §10 — Incremental adoption, codemod tool
- [Conformance](/spec/conformance/) — §11 — Gateway and SDK conformance requirements

## Design requirements

| ID | Requirement |
|---|---|
| R1 | **Build-tool agnostic.** Must work with any frontend framework or bundler without build-time plugins. |
| R2 | **Security-classified.** Must distinguish between public, sensitive, and server-only variables. |
| R3 | **Integrity-verified.** The injected configuration must be verifiable by the client SDK. |
| R4 | **Synchronously accessible.** Public variables must be available immediately on page load. |
| R5 | **Zero application dependencies.** The client SDK must have zero runtime dependencies. |
| R6 | **Minimal footprint.** Gateway under 8MB, SDK under 2KB gzipped. |
| R7 | **Container-native.** Must integrate with Docker and Kubernetes via standard env vars. |
| R8 | **Incrementally adoptable.** Must not require all-or-nothing migration. |
| R9 | **Observable.** Must emit structured logs and metrics for injection events. |
| R10 | **Hot-reloadable (optional).** Must support live config updates without page reload. |

## Comparison with existing solutions

| Feature | `envsubst` | `runtime-env-cra` | `@import-meta-env` | `react-env` | **REP** |
|---|:---:|:---:|:---:|:---:|:---:|
| Framework agnostic | Yes | No | Partial | No | **Yes** |
| No build tool plugin | Yes | No | No | No | **Yes** |
| Security classification | -- | -- | -- | -- | **Yes** |
| Encrypted sensitive vars | -- | -- | -- | -- | **Yes** |
| Integrity verification | -- | -- | -- | -- | **Yes** |
| Secret leak detection | -- | -- | -- | -- | **Yes** |
| Hot reload | -- | -- | -- | -- | **Yes** |
| No Node.js in prod | Partial | No | No | No | **Yes** |
| Formal specification | -- | -- | -- | -- | **Yes** |
| `FROM scratch` compatible | -- | -- | -- | -- | **Yes** |

## FAQ

**Q: Why not use a service mesh / API gateway?**
Service meshes operate at L4/L7 for service-to-service communication. They don't inject configuration into HTML. REP is complementary.

**Q: Why not use SSR frameworks that support runtime env vars?**
SSR solves this for supported frameworks, but not all apps need SSR, it couples you to a specific framework, and many organisations have existing SPAs. REP works with any SPA.

**Q: Isn't the SENSITIVE tier just security through obscurity?**
Partially — see the [Security Model](/spec/security-model/) for an honest assessment. SENSITIVE raises the bar against casual exposure while making intentional access auditable. For true secrets, use the SERVER tier.

---

The full source of REP-RFC-0001 is available at [`spec/REP-RFC-0001.md`](https://github.com/ruachtech/rep/blob/main/spec/REP-RFC-0001.md).


---

# Security Model Specification — Threat Model and Analysis

> Formal threat model for the Runtime Environment Protocol. Seven threat analyses covering XSS, CDN compromise, session key theft, env var leaks, and more. Hardening recommendations.

Source: https://rep-protocol.dev/spec/security-model/

```
Document:  REP Security Model
Version:   0.1.0
Status:    Active
Authors:   Olamide Adebayo (Ruach Tech)
License:   CC BY 4.0
```

> **Note**
>
> For a practical guide to REP's security properties, see [Security Model (Concepts)](/concepts/security-model/). This page is the formal specification document.

- [Security Model (Concepts)](/concepts/security-model/) — Practical guide — threat analysis, hardening, monitoring recommendations

The concepts page contains the full content of this specification, reformatted for easier navigation. It covers:

- Fundamental axiom and trust boundaries
- All 7 threat analyses (T1-T7) with severity, mitigations, and residual risk
- Variable classification decision tree with common misclassifications
- Production hardening recommendations (gateway config, FROM scratch Dockerfile, CSP headers)
- Monitoring and alerting setup
- Known limitations

---

The full source document is at [`spec/SECURITY-MODEL.md`](https://github.com/ruachtech/rep/blob/main/spec/SECURITY-MODEL.md).


---

# Conformance Requirements — Gateway and SDK Compliance

> MUST-level requirements for REP-conformant gateway and SDK implementations. 10 gateway requirements, 6 SDK requirements, and 5 optional features per RFC 2119.

Source: https://rep-protocol.dev/spec/conformance/

An implementation is **REP-conformant** if it satisfies the requirements below. This page is extracted from REP-RFC-0001 Section 11.

## Gateway conformance (MUST)

A conformant gateway implementation MUST:

1. Read only `REP_*` prefixed environment variables
2. Classify variables into exactly three tiers based on prefix (`PUBLIC`, `SENSITIVE`, `SERVER`)
3. Strip the classification prefix from variable names in the payload
4. Reject startup if variable names collide after prefix stripping
5. Run secret detection guardrails on PUBLIC tier variables
6. Inject a `<script id="__rep__" type="application/json">` block into HTML responses
7. Compute and include an HMAC-SHA256 integrity token
8. Encrypt SENSITIVE tier variables using AES-256-GCM
9. Issue single-use, time-limited session keys via `/rep/session-key`
10. Never transmit SERVER tier variables to the client under any circumstances

## Client SDK conformance (MUST)

A conformant SDK implementation MUST:

1. Read from `<script id="__rep__">` synchronously on import
2. Verify payload integrity on initialization (SRI hash)
3. Expose `get()` as a synchronous function
4. Expose `getSecure()` as an async function
5. Make no network calls during initialization
6. Freeze the public variable object to prevent mutation

## Optional features (MAY)

Conformant implementations MAY implement:

1. Hot reload via Server-Sent Events
2. Manifest file validation at startup
3. TypeScript type generation from manifest
4. Framework-specific adapters (React hooks, Vue composables, Svelte stores)
5. Codemod tooling for migration

## Notes

- "MUST", "SHOULD", and "MAY" follow [RFC 2119](https://tools.ietf.org/html/rfc2119) conventions
- The reference implementation (gateway in Go, SDK in TypeScript) satisfies all MUST requirements and implements all optional features
- Alternative implementations need only satisfy the MUST requirements to be conformant


---

# Contributing to REP

> How to contribute to the Runtime Environment Protocol. Development setup with pnpm and Go, commit conventions, code style for Go and TypeScript, testing, and the automated release process.

Source: https://rep-protocol.dev/contributing/

## Getting started

### Prerequisites

- **Node.js** >= 20.0.0
- **pnpm** >= 9.0.0 — `npm install -g pnpm`
- **Go** >= 1.24.5 (for gateway development only)

### Setup

```bash
git clone https://github.com/ruachtech/rep.git
cd rep
pnpm install
pnpm run build
pnpm run test
```

For gateway:
```bash
cd gateway
go test -race ./...
```

## Project structure

```
rep/
├── spec/           # Protocol specification documents
├── schema/         # JSON schemas for payload and manifest
├── gateway/        # Go reference implementation (stdlib only)
├── sdk/            # @rep-protocol/sdk (zero runtime deps)
├── cli/            # @rep-protocol/cli
├── adapters/       # React, Vue, Svelte adapters
├── codemod/        # Migration tool
├── docs/           # This documentation site (Astro/Starlight)
└── examples/       # Example applications
```

## Commit conventions

This project uses [Conventional Commits](https://www.conventionalcommits.org/). Every commit to `main` must follow this format:

```
<type>(<scope>): <description>

[optional body]
```

### Types

| Type | Effect | Example |
|---|---|---|
| `fix` | Patch release | `fix(sdk): handle missing meta field` |
| `feat` | Minor release | `feat(gateway): add poll mode for hot reload` |
| `feat!` | Major release | `feat!(sdk)!: rename getSecure to decrypt` |
| `docs` | No release | `docs(spec): clarify SRI verification` |
| `chore` | No release | `chore: update dev dependencies` |
| `refactor` | No release | `refactor(gateway): extract inject middleware` |
| `test` | No release | `test(sdk): add hot reload tests` |
| `perf` | No release | `perf(gateway): reduce allocation in inject` |

### Scopes

`sdk`, `gateway`, `cli`, `react`, `vue`, `svelte`, `codemod`, `spec`, `docs`

## Code style

### Go (Gateway)

- **Standard library only.** No third-party dependencies.
- Structured logging via `log/slog`
- Error wrapping: `fmt.Errorf("context: %w", err)`
- No `init()` functions
- Tests use stdlib only (`testing`, `net/http/httptest`)
- Use `t.Setenv()` for env var tests (never `os.Setenv` directly)
- Run with `-race` flag

### TypeScript (SDK, CLI, Adapters)

- Zero runtime dependencies for the SDK
- Vitest + jsdom for testing
- `vi.resetModules()` before each SDK test (because `_init()` runs on module load)
- DOM cleanup in `beforeEach`

## Testing

```bash
# All TypeScript packages
pnpm run test

# Gateway (from gateway/)
go test -race ./...

# Specific package
pnpm --filter @rep-protocol/sdk run test
```

## Release process

Releases are automated via [release-please](https://github.com/googleapis/release-please):

1. Push conventional commits to `main`
2. Release-please creates/updates a Release PR with version bumps and changelogs
3. Merging the Release PR triggers npm publishing for all packages
4. The gateway is versioned independently via `gateway/VERSION` and released through GoReleaser

> **Caution**
>
> Do not manually bump versions in `package.json` or create release tags. The automation handles this.

## PR guidelines

- Branch from `main`
- Keep PRs focused on a single change
- Include tests for new functionality
- Use squash-merge with a conventional commit message


---

# REP — Runtime Environment Protocol | Secure Runtime Env Vars for Frontend Apps

> Inject environment variables into browser apps at container runtime — not build time. AES-256 encryption, secret detection, hot reload. Build once, deploy anywhere.

Source: https://rep-protocol.dev/

<div style="max-width: 720px; margin: 0 auto 2rem;">
  <video controls playsinline preload="metadata" style="width: 100%; border-radius: 8px; border: 1px solid var(--sl-color-gray-5);">
    <source src="https://github.com/RuachTech/rep/releases/download/v0.1.3/rep-gateway-demo.mp4" type="video/mp4" />
  </video>
  <p style="text-align: center; font-size: 0.85rem; color: var(--sl-color-gray-3); margin-top: 0.5rem;">Same frontend image, different environment, dynamic variables — no rebuild, no redeploy.</p>
</div>

## The Problem

Every frontend framework resolves environment variables at **build time** — `process.env.API_URL` becomes a hardcoded string in your JavaScript bundle. This creates problems that compound in production:

  **One build per environment**

  Your staging bundle can't be promoted to production. You rebuild for every environment, breaking the container promise of "build once, run anywhere."

  **No security model**

  All variables are treated equally. API keys, analytics tokens, and public URLs all end up as plaintext strings in your bundle — visible to anyone who opens View Source.

  **Config changes require redeployment**

  Need to rotate an API key or flip a feature flag? Rebuild, re-test, redeploy. Even if your backend can hot-swap config, your frontend can't.

  **Secrets leak into build logs**

  CI/CD pipelines pass secrets as build args. They appear in Docker layer history, build logs, and cached artifacts — creating supply chain risk.

## What REP Does

REP is an open protocol and reference implementation that **decouples environment variables from the build process entirely**. A lightweight gateway reads variables at startup, classifies them by security tier, encrypts sensitive values, and injects them into HTML responses — whether you're running containers, static builds, or local development.

  **Three Security Tiers**

  **PUBLIC** — plaintext, synchronous access. **SENSITIVE** — AES-256-GCM encrypted, decrypted on demand. **SERVER** — never sent to the browser. Classification by naming convention eliminates ambiguity.

  **Encryption + Integrity**

  Sensitive variables are encrypted with ephemeral keys generated at startup. Every payload carries an HMAC-SHA256 integrity token and SRI hash to detect tampering in transit.

  **Secret Detection Guardrails**

  Entropy analysis and known-format matching (AWS keys, JWTs, Stripe keys, GitHub tokens) catch misclassified secrets before they reach the browser. Strict mode makes warnings into hard failures.

  **Hot Reload via SSE**

  Config changes push to every connected browser via Server-Sent Events. No page reload, no redeployment. Edit an env file or rotate a ConfigMap — the UI updates live.

## Works Everywhere

REP operates at the **infrastructure layer** in production — no build-tool plugin required, no framework coupling. It works with any frontend stack that produces HTML. Optional dev-time plugins exist purely for local DX (see below).

  **Containers**

  Reverse proxy mode sits in front of nginx, caddy, or any upstream. Embedded mode serves static files directly from a `FROM scratch` image.

  **Static Builds**

  Build your app once with `npm run build`. The gateway injects config into the static HTML at serve time — same artifact for every environment.

  **Local Development**

  Install the [Vite](/reference/plugins/vite/) or [Next.js](/reference/plugins/next/) plugin for zero-config `dev` support, or the CLI wraps the gateway to proxy any dev server with hot reload.

  **Any Framework**

  First-party adapters for React, Vue, and Svelte. A zero-dependency TypeScript SDK works with anything — Angular, vanilla JS, or your custom setup.

## Compared to Existing Solutions

| Approach | Security Tiers | Encrypted Vars | Integrity Check | Hot Reload | Standalone Binary |
|---|:---:|:---:|:---:|:---:|:---:|
| `envsubst` / `sed` on bundles | -- | -- | -- | -- | -- |
| Fetch `/config.json` at runtime | -- | -- | -- | -- | -- |
| `window.__ENV__` via shell script | -- | -- | -- | -- | -- |
| Build-tool plugins (dotenv, etc.) | -- | -- | -- | -- | -- |
| **REP** | **3-tier** | **AES-256-GCM** | **HMAC + SRI** | **SSE** | **~7MB Go** |

## Quick Example

  **SDK Usage**

  ```typescript
  import { rep } from '@rep-protocol/sdk';

  // Synchronous — no loading state needed
  const apiUrl = rep.get('API_URL');
  const flags = rep.get('FEATURE_FLAGS');

  // Encrypted — decrypted on demand via session key
  const key = await rep.getSecure('ANALYTICS_KEY');

  // Hot reload — react to config changes live
  rep.onChange('FEATURE_FLAGS', (newValue) => {
    console.log('Flags updated:', newValue);
  });
  ```

  **Docker Compose**

  ```yaml
  # Same image, different config — true build-once, deploy-anywhere
  services:
    frontend-staging:
      image: myapp:latest
      environment:
        REP_PUBLIC_API_URL: "https://api.staging.example.com"
        REP_SENSITIVE_ANALYTICS_KEY: "UA-XXXXX-staging"
        REP_SERVER_INTERNAL_SECRET: "never-reaches-browser"

    frontend-prod:
      image: myapp:latest  # SAME IMAGE
      environment:
        REP_PUBLIC_API_URL: "https://api.example.com"
        REP_SENSITIVE_ANALYTICS_KEY: "UA-XXXXX-prod"
        REP_SERVER_INTERNAL_SECRET: "also-never-reaches-browser"
  ```

  **Variable Tiers**

  ```bash
  # PUBLIC — plaintext in page source, rep.get()
  REP_PUBLIC_API_URL=https://api.example.com

  # SENSITIVE — AES-256-GCM encrypted, await rep.getSecure()
  REP_SENSITIVE_ANALYTICS_KEY=UA-12345-1

  # SERVER — never leaves the gateway process
  REP_SERVER_DB_PASSWORD=never-reaches-browser
  ```

## Project Components

  **Gateway**

  Go binary (~7MB). Zero dependencies. `FROM scratch` compatible. Proxy or embedded mode.

  **SDK**

  TypeScript. Zero runtime deps. ~1.5KB gzipped. Synchronous `get()`, async `getSecure()`.

  **CLI**

  `rep validate`, `rep typegen`, `rep lint`, `rep dev`. Full development workflow.

  **Adapters**

  First-party React, Vue, and Svelte adapters with hot-reload-aware hooks and stores.

  **Build-Tool Plugins**

  Vite (`repPlugin()`) and Next.js (`RepScript`) plugins inject the same payload during `npm run dev` — no gateway needed locally.

  **Codemod**

  `npx @rep-protocol/codemod` automates migration from Vite, CRA, or Next.js `process.env`/`import.meta.env` reads to `rep.get()`.

## Specification Status

| Document | Status | Version |
|---|---|---|
| [REP-RFC-0001](/spec/rfc-0001/) | Active | 0.1.0 |
| [Security Model](/spec/security-model/) | Active | 0.1.0 |
| [Conformance](/spec/conformance/) | Active | 0.1.0 |

Specification documents are licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Code is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).