NestJS

This guide adds Bunkhouse to a server-rendered NestJS application. Every file shown below is part of a runnable example app that is tested end to end against the real Bunkhouse API and embed.

Tested setup


Framework	NestJS 12.3.2 with the Express platform adapter, MVC views rendered by `hbs` 4.4, `express-session` 1.19
Runtime	Node.js 24 (v24.22.2 in the tested image), TypeScript compiled to JavaScript
Example	`apps/docs/integrations/nestjs/` in the Bunkhouse repository

You need:

Your application’s exact origin registered on the site (for example https://app.example.com).
The site’s public key (pk_...).
For identity tokens (recommended): a signing secret (ss_...) and its key ID from the site’s Keys page.
For server mint instead: a mint key (sk_...).
Existing sign-in that puts the authenticated user on the request (req.user, as Passport strategies and auth guards do). The example uses express-session with two demo users; your own authentication takes its place. Bunkhouse only needs the signed-in user’s stable ID on the server.

File	Purpose
`src/config.ts`	Validates the public Bunkhouse configuration at startup
`src/agent.controller.ts`	`GET /api/agent-identity` and `POST /api/agent-session`
`src/csp.ts`	Your Content-Security-Policy with the Bunkhouse sources added
`views/partials/agent-embed-*.hbs`	The script tags for one installation mode
`public/agent-identity.js`, `public/agent-auth-headers.js`	Page hooks, loaded before the loader

Identity token (recommended)

Set the server environment. Only AGENT_PUBLIC_KEY and the origins ever reach the browser:

AGENT_PUBLIC_KEY=pk_...
AGENT_SIGNING_SECRET=ss_...        # server only
AGENT_SIGNING_KID=...              # key ID shown with the signing secret
AGENT_ALLOWED_ORIGINS='["https://app.example.com"]'
# AGENT_API_BASE and AGENT_EMBED_ORIGIN default to https://api.bunkhouse.ai and https://embed.bunkhouse.ai

// Bunkhouse public configuration, validated once at startup. Signing and mint credentials are read
// only by the endpoints that use them, so each mode needs only its own secret.
function exactOrigin(name: string, value: string): string {
  const url = new URL(value);
  if (url.origin !== value) throw new Error(`${name} must be an exact origin like https://app.example.com`);
  return value;
}

const publicKey = process.env.AGENT_PUBLIC_KEY ?? "";
if (!publicKey.startsWith("pk_")) throw new Error("AGENT_PUBLIC_KEY must be the site's public key (pk_...)");

const origins: unknown = JSON.parse(process.env.AGENT_ALLOWED_ORIGINS ?? "[]");
if (!Array.isArray(origins) || origins.length === 0) throw new Error('AGENT_ALLOWED_ORIGINS must be a JSON array such as ["https://app.example.com"]');

export const agentConfig = {
  publicKey,
  allowedOrigins: origins.map((o) => exactOrigin("AGENT_ALLOWED_ORIGINS", String(o))),
  apiBase: exactOrigin("AGENT_API_BASE", process.env.AGENT_API_BASE ?? "https://api.bunkhouse.ai"),
  embedOrigin: exactOrigin("AGENT_EMBED_ORIGIN", process.env.AGENT_EMBED_ORIGIN ?? "https://embed.bunkhouse.ai"),
};

The controller signs a ten-minute HS256 token for the user your authentication already attached to the request. It rejects other methods (405 via an @All handler declared after the real one), requests whose Sec-Fetch-Site is not same-origin (403) and signed-out users (401, never a login redirect), and marks every response Cache-Control: no-store. The subject comes only from req.user, never from the query, body or headers. The same controller contains the server mint endpoint used by the alternative below.

// Bunkhouse endpoints: GET /api/agent-identity (identity token mode) and POST /api/agent-session
// (server mint mode). Both vouch only for the user your existing authentication put on the request.
import { createHmac } from "node:crypto";
import { All, Controller, Get, Post, Req, Res, createParamDecorator, type ExecutionContext } from "@nestjs/common";
import type { Request, Response } from "express";
import { agentConfig } from "./config";

/** Your existing authentication: the signed-in user it attached to the request (req.user), or null. */
export const CurrentUser = createParamDecorator(
  (_data: unknown, ctx: ExecutionContext): { id: string } | null => ctx.switchToHttp().getRequest().user ?? null,
);

const base64url = (value: object) => Buffer.from(JSON.stringify(value)).toString("base64url");

/** HS256 identity token: kid header, sub = stable opaque user ID, aud = public key, 10 minutes. */
export function signIdentityToken(userId: string, secret: string, kid: string): string {
  const iat = Math.floor(Date.now() / 1000);
  const header = base64url({ alg: "HS256", typ: "JWT", kid });
  const payload = base64url({ sub: userId, aud: agentConfig.publicKey, iat, exp: iat + 600 });
  const signature = createHmac("sha256", secret).update(`${header}.${payload}`).digest("base64url");
  return `${header}.${payload}.${signature}`;
}

function notConfigured(res: Response, variable: string) {
  console.error(`Bunkhouse: ${variable} is not set`);
  res.status(503).json({ error: "not_configured" });
}

const methodNotAllowed = (res: Response, allow: string) =>
  res.set({ Allow: allow, "Cache-Control": "no-store" }).status(405).json({ error: "method_not_allowed" });

@Controller("api")
export class AgentController {
  @Get("agent-identity")
  identity(@Req() req: Request, @Res() res: Response, @CurrentUser() user: { id: string } | null) {
    res.set("Cache-Control", "no-store");
    if (req.get("sec-fetch-site") !== "same-origin") return res.status(403).json({ error: "forbidden" });
    if (!user) return res.status(401).json({ error: "unauthorized" });
    const { AGENT_SIGNING_SECRET: secret, AGENT_SIGNING_KID: kid } = process.env;
    if (!secret) return notConfigured(res, "AGENT_SIGNING_SECRET");
    if (!kid) return notConfigured(res, "AGENT_SIGNING_KID");
    res.json({ identityToken: signIdentityToken(String(user.id), secret, kid) });
  }

  @All("agent-identity")
  identityMethodNotAllowed(@Res() res: Response) {
    methodNotAllowed(res, "GET");
  }

  @Post("agent-session")
  async session(@Req() req: Request, @Res() res: Response, @CurrentUser() user: { id: string } | null) {
    res.set("Cache-Control", "no-store");
    // The embed's POST carries no CSRF token; these three checks are this route's CSRF defense.
    const origin = req.get("origin");
    if (!origin || !agentConfig.allowedOrigins.includes(origin) || req.get("x-agent-embed") !== "1" || req.get("sec-fetch-site") !== "same-origin") {
      return res.status(403).json({ error: "forbidden" });
    }
    if (!user) return res.status(401).json({ error: "unauthorized" });
    const key = process.env.AGENT_EMBED_SECRET_KEY;
    if (!key) return notConfigured(res, "AGENT_EMBED_SECRET_KEY");
    try {
      const upstream = await fetch(`${agentConfig.apiBase}/v1/embed/sessions`, {
        method: "POST",
        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
        body: JSON.stringify({ publicKey: agentConfig.publicKey, mode: "signed", userId: String(user.id), origin }),
        signal: AbortSignal.timeout(15_000),
      });
      const body = Buffer.from(await upstream.arrayBuffer());
      res.status(upstream.status).type(upstream.headers.get("content-type") ?? "application/json").send(body);
    } catch {
      res.status(502).json({ error: "session_service_unavailable" });
    }
  }

  @All("agent-session")
  sessionMethodNotAllowed(@Res() res: Response) {
    methodNotAllowed(res, "POST");
  }
}

Register AgentController in a module and make sure your authentication runs first. The CurrentUser parameter decorator is the seam to your authentication: it reads the user your session middleware, Passport strategy or guard set on the request, or null. In the example, session middleware does that:

app.use(
  session({
    name: "example.sid",
    secret: SESSION_SECRET!,
    resave: false,
    saveUninitialized: false,
    // Secure everywhere except the loopback HTTP test origin.
    cookie: { httpOnly: true, sameSite: "lax", secure: APP_ORIGIN.startsWith("https://") },
  }),
);
// Your authentication attaches the signed-in user to the request; the agent endpoints read req.user.
app.use((req: Request, _res: Response, next: NextFunction) => {
  req.user = req.session.user;
  next();
});

In the page head, load the identity hook, then the getAuthHeaders hook (shown below), then the loader, all before your application’s own scripts: window.AgentEmbedConfig must be defined before the loader runs. The hooks are external same-origin scripts, so no inline script needs a CSP exception:

{{!-- Identity token mode (recommended): both page hooks, then the loader, before the app's scripts. --}}
<script src="/agent-identity.js" nonce="{{nonce}}"></script>
<script src="/agent-auth-headers.js" nonce="{{nonce}}"></script>
<script src="{{agent.embedOrigin}}/embed.js" nonce="{{nonce}}"
  data-public-key="{{agent.publicKey}}" data-hints-url="/agent-hints.json"></script>

// Identity token mode: the embed calls this hook whenever it starts a session for the signed-in user.
window.AgentEmbedConfig = {
  ...window.AgentEmbedConfig,
  getIdentityToken: async () => {
    const res = await fetch("/api/agent-identity", { credentials: "same-origin", cache: "no-store" });
    if (!res.ok) throw new Error("Not signed in");
    return (await res.json()).identityToken;
  },
};

{{#if csrfToken}}<meta name="csrf-token" content="{{csrfToken}}" />{{/if}}
{{> (lookup . "embedPartial") }}
<!-- The application's own JavaScript comes after the loader. -->
<script src="/app.js" nonce="{{nonce}}" defer></script>

The example layout includes one of the three agent-embed-* partials, selected by a test-only ?mode= switch. Your application uses exactly one.

Server mint alternative

Instead of the identity hook, add data-session-endpoint to the loader. Do not keep agent-identity.js on the page: when getIdentityToken is defined it takes precedence.

{{!-- Server mint mode: no identity hook; the auth-headers hook, then the loader, which posts to the same-origin session endpoint. --}}
<script src="/agent-auth-headers.js" nonce="{{nonce}}"></script>
<script src="{{agent.embedOrigin}}/embed.js" nonce="{{nonce}}"
  data-public-key="{{agent.publicKey}}" data-hints-url="/agent-hints.json"
  data-session-endpoint="/api/agent-session"></script>

POST /api/agent-session in src/agent.controller.ts above accepts only requests with an Origin from AGENT_ALLOWED_ORIGINS, X-Agent-Embed: 1 and Sec-Fetch-Site: same-origin (403 otherwise), authenticates the request (401), then creates the session with the mint key and returns the API’s status and body unchanged with Cache-Control: no-store. If the API is unreachable it returns 502 without details. Set AGENT_EMBED_SECRET_KEY=sk_... on the server; the identity endpoint does not need it.

NestJS has no built-in CSRF protection. If you add a CSRF middleware, exempt only /api/agent-session: the embed’s POST carries no CSRF token, and the three header checks are that route’s protection. If a global auth guard redirects unauthenticated users, keep it from redirecting these two API routes; they must answer 401.

Anonymous alternative

Anonymous sessions need no identity hook or session endpoint: the loader, preceded only by the getAuthHeaders hook if your API needs extra headers. Enable anonymous access for the site in the dashboard first and set its monthly token and spend limits; usage is charged to your account’s credit and stops at a limit. Anyone who can load your page can start one, so it is not proof of identity.

{{!-- Anonymous mode (enable it for the site first): no identity hook; the auth-headers hook, then the loader. --}}
<script src="/agent-auth-headers.js" nonce="{{nonce}}"></script>
<script src="{{agent.embedOrigin}}/embed.js" nonce="{{nonce}}"
  data-public-key="{{agent.publicKey}}" data-hints-url="/agent-hints.json"></script>

The example signs in and out with ordinary form posts that redirect back to the same page. Every account change therefore loads a new document, and a new document starts a new embed with no session, so the previous user’s session can never carry over. The session cookie is HttpOnly and SameSite, and the session is regenerated on login (see the session excerpt above).

If your NestJS app changes the signed-in user without a full page load (a fetch login, a single-page frontend), call window.AgentEmbed?.resetSession() right after the login, logout or account switch succeeds and before the new user’s requests. The React, Vue and Angular guides show that pattern. Render the loader once in the layout, not in per-page views.

Auth headers, user IDs and CSP

The assistant calls your API with the page’s cookies; supply any extra header your API requires with getAuthHeaders. The example’s session owns a random CSRF token, rendered into a <meta> tag for signed-in users and checked on every write as X-CSRF-Token:

// The app's own CSRF token (rendered by the server for the signed-in session) for the assistant's calls
// to this app's API. Values never reach the model or the sandbox.
window.AgentEmbedConfig = {
  ...window.AgentEmbedConfig,
  getAuthHeaders: () => {
    const token = document.querySelector('meta[name="csrf-token"]')?.content;
    return token ? { "X-CSRF-Token": token } : {};
  },
};

Every partial loads it before the loader. It merges into window.AgentEmbedConfig, so it works with the identity hook in either order. Its values never reach the model or the sandbox.

Send a stable, opaque user ID (the example’s fixture-alice), not a name or email address.

Add the Bunkhouse sources to your existing policy rather than replacing it. The example registers this middleware with app.use() before the session middleware; it sets a fresh nonce per response, which the views put on their script tags. No 'unsafe-inline' or 'unsafe-eval' is needed. If you use helmet, add the same sources to its contentSecurityPolicy directives instead:

// The app's existing Content-Security-Policy with the Bunkhouse sources added: the embed origin to
// script-src and frame-src, the API to connect-src. A fresh nonce per response (res.locals.cspNonce)
// goes on the page's script tags.
import { randomBytes } from "node:crypto";
import type { NextFunction, Request, Response } from "express";
import { agentConfig } from "./config";

export function contentSecurityPolicy(_req: Request, res: Response, next: NextFunction) {
  const nonce = randomBytes(16).toString("base64");
  res.locals.cspNonce = nonce;
  res.set(
    "Content-Security-Policy",
    [
      "default-src 'self'",
      `script-src 'self' 'nonce-${nonce}' ${agentConfig.embedOrigin}`,
      `style-src 'self' 'nonce-${nonce}'`,
      `frame-src ${agentConfig.embedOrigin}`,
      `connect-src 'self' ${agentConfig.apiBase}`,
      "img-src 'self' data:",
      "object-src 'none'",
      "base-uri 'self'",
      "form-action 'self'",
      "frame-ancestors 'self'",
    ].join("; "),
  );
  next();
}

Verify

From a checkout of the Bunkhouse repository, with Docker and local Supabase running:

node tests/framework-integrations/run.ts nestjs

The run builds the example image, starts it against a fresh local site and drives the real pane in Chromium: identity, mint and anonymous sessions, endpoint guards, sign-out and account switches, discovery of the page’s startup request, a CSRF-protected write through getAuthHeaders, CSP and secret checks. In your own app, sign in and open the Assistant launcher: the first message creates a signed session.

Symptom	Check
`/api/agent-identity` returns 401	Your authentication does not run before the controller, or does not set `req.user`.
A login redirect instead of 401	A global guard or filter redirects unauthenticated requests; let these routes respond with 401.
403 from either endpoint	The request is cross-site or missing `Sec-Fetch-Site`; for mint, `Origin` must exactly match `AGENT_ALLOWED_ORIGINS` and the loader must carry `data-session-endpoint`. A CSRF middleware must exempt only `/api/agent-session`.
405 for GET or POST	The `@All` handlers must be declared after the `@Get`/`@Post` handlers in the controller.
503	The signing secret, key ID or mint key for the mode you use is not set.
The pane reports a CSP block	Add the embed origin to `script-src` and `frame-src` and the API to `connect-src`.
Startup requests are not discovered	The loader must come before your application’s scripts in the head.
Two launchers	Render the loader once, in the layout.
A secret in page source	Only `AGENT_PUBLIC_KEY` and origins belong in views; keep `ss_` and `sk_` values in server environment variables.

Installation, Security and the Page API
NestJS: Controllers, Authentication, Model-View-Controller