feat(agent-bff): mode 1 oauth session core (issue tokens)

packages/agent-bff/package.json

@@ -31,10 +31,14 @@
     "test": "jest"
   },
   "dependencies": {
+    "@forestadmin/forestadmin-client": "1.40.3",
+    "@koa/bodyparser": "^6.1.0",
+    "jsonwebtoken": "^9.0.3",
     "koa": "^3.0.1",
     "zod": "4.3.6"
   },
   "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.1",
     "@types/koa": "^2.13.5",
     "@types/supertest": "^6.0.2",
     "supertest": "^7.1.3"

packages/agent-bff/src/cli-core.ts

@@ -1,17 +1,93 @@
+import type { BFFConfig } from './config/env-config';
 import type { Logger } from './ports/logger-port';
+import type { Middleware } from 'koa';
+
+import { bodyParser } from '@koa/bodyparser';
 
 import createConsoleLogger from './adapters/console-logger';
 import { parseConfig } from './config/env-config';
 import { extractErrorMessage } from './errors';
 import BFFHttpServer from './http/bff-http-server';
+import ForestServerClient from './oauth/forest-server-client';
+import createOAuthRoutes from './oauth/oauth-routes';
+import createInMemorySessionStore from './oauth/session-store';
+import createTokenCipher from './oauth/token-cipher';
 import version from './version';
 
+const BODY_LIMIT = '16kb';
+const SESSION_TTL_SECONDS = 24 * 60 * 60;
+
+interface ResolvedOAuthConfig {
+  forestServerUrl: string;
+  forestEnvSecret: string;
+  forestAppUrl: string;
+  forestAuthSecret: string;
+  tokenEncryptionKey: string;
+}
+
+function resolveOAuthConfig(config: BFFConfig): ResolvedOAuthConfig | undefined {
+  const { forestServerUrl, forestEnvSecret, forestAppUrl, forestAuthSecret, tokenEncryptionKey } =
+    config;
+
+  if (
+    forestServerUrl &&
+    forestEnvSecret &&
+    forestAppUrl &&
+    forestAuthSecret &&
+    tokenEncryptionKey
+  ) {
+    return { forestServerUrl, forestEnvSecret, forestAppUrl, forestAuthSecret, tokenEncryptionKey };
+  }
+
+  return undefined;
+}
+
+async function buildOAuthMiddlewares(config: BFFConfig, logger: Logger): Promise<Middleware[]> {
+  const oauthConfig = resolveOAuthConfig(config);
+
+  if (!oauthConfig) {
+    logger('Warn', 'OAuth routes disabled: required configuration is missing');
+
+    return [];
+  }
+
+  const { forestServerUrl, forestEnvSecret, forestAppUrl, forestAuthSecret, tokenEncryptionKey } =
+    oauthConfig;
+
+  const serverClient = new ForestServerClient({ forestServerUrl, envSecret: forestEnvSecret });
+  const environmentId = await serverClient.fetchEnvironmentId();
+
+  const sessionStore = createInMemorySessionStore({
+    cipher: createTokenCipher(tokenEncryptionKey),
+    now: () => Date.now(),
+    sessionTtlSeconds: SESSION_TTL_SECONDS,
+  });
+
+  const oauthRoutes = createOAuthRoutes({
+    serverClient,
+    sessionStore,
+    forestAppUrl,
+    authSecret: forestAuthSecret,
+    environmentId,
+    logger,
+  });
+
+  return [bodyParser({ jsonLimit: BODY_LIMIT }), oauthRoutes];
+}
+
 export default async function runCli(
   env: NodeJS.ProcessEnv,
   logger: Logger = createConsoleLogger(),
 ): Promise<BFFHttpServer> {
   const config = parseConfig(env);
-  const server = new BFFHttpServer({ port: config.httpPort, version, config, logger });
+  const middlewares = await buildOAuthMiddlewares(config, logger);
+  const server = new BFFHttpServer({
+    port: config.httpPort,
+    version,
+    config,
+    logger,
+    middlewares,
+  });
 
   await server.start();
 

packages/agent-bff/src/config/env-config.ts

@@ -23,13 +23,16 @@ export interface BFFConfig {
   forestServerUrl?: string;
   forestAppUrl?: string;
   agentUrl?: string;
+  tokenEncryptionKey?: string;
   httpPort: number;
   presence: PresenceMap;
   hasAllRequired: boolean;
 }
 
 const DECIMAL_INTEGER = /^\d+$/;
 const MAX_PORT = 65535;
+const ENCRYPTION_KEY_BYTES = 32;
+const BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
 const HTTP_URL_SCHEMA = z.url({ protocol: /^https?$/ });
 
 function normalize(value: string | undefined): string | undefined {
@@ -55,6 +58,22 @@ function isHttpUrl(value: string): boolean {
   return !/\s/.test(value) && HTTP_URL_SCHEMA.safeParse(value).success;
 }
 
+function isValidEncryptionKey(value: string): boolean {
+  return BASE64_PATTERN.test(value) && Buffer.from(value, 'base64').length === ENCRYPTION_KEY_BYTES;
+}
+
+function parseEncryptionKey(raw: string | undefined): string | undefined {
+  const value = normalize(raw);
+
+  if (value !== undefined && !isValidEncryptionKey(value)) {
+    throw new ConfigurationError(
+      `Invalid configuration: BFF_TOKEN_ENCRYPTION_KEY must be base64-encoded and exactly ${ENCRYPTION_KEY_BYTES} bytes (AES-256).`,
+    );
+  }
+
+  return value;
+}
+
 export function parseConfig(env: NodeJS.ProcessEnv): BFFConfig {
   const normalized = Object.fromEntries(
     REQUIRED_KEYS.map(key => [key, normalize(env[key])]),
@@ -72,14 +91,17 @@ export function parseConfig(env: NodeJS.ProcessEnv): BFFConfig {
     REQUIRED_KEYS.map(key => [key, normalized[key] !== undefined]),
   ) as PresenceMap;
 
+  const tokenEncryptionKey = parseEncryptionKey(env.BFF_TOKEN_ENCRYPTION_KEY);
+
   return {
     forestAuthSecret: normalized.FOREST_AUTH_SECRET,
     forestEnvSecret: normalized.FOREST_ENV_SECRET,
     forestServerUrl: normalized.FOREST_SERVER_URL,
     forestAppUrl: normalized.FOREST_APP_URL,
     agentUrl: normalized.AGENT_URL,
+    tokenEncryptionKey,
     httpPort: parsePort(env.HTTP_PORT),
     presence,
-    hasAllRequired: REQUIRED_KEYS.every(key => presence[key]),
+    hasAllRequired: REQUIRED_KEYS.every(key => presence[key]) && tokenEncryptionKey !== undefined,
   };
 }

packages/agent-bff/src/http/bff-http-server.ts

@@ -1,6 +1,7 @@
 import type { BFFConfig } from '../config/env-config';
 import type { Logger } from '../ports/logger-port';
 import type { Server } from 'http';
+import type { Middleware } from 'koa';
 
 import http from 'http';
 import Koa from 'koa';
@@ -12,6 +13,7 @@ export interface BFFHttpServerOptions {
   version: string;
   config: BFFConfig;
   logger?: Logger;
+  middlewares?: Middleware[];
 }
 
 export default class BFFHttpServer {
@@ -41,6 +43,10 @@ export default class BFFHttpServer {
 
       await next();
     });
+
+    for (const middleware of this.options.middlewares ?? []) {
+      this.app.use(middleware);
+    }
   }
 
   async start(): Promise<void> {

packages/agent-bff/src/index.ts

@@ -7,3 +7,18 @@ export { default as DEFAULT_BFF_PORT } from './defaults';
 export { default as createConsoleLogger } from './adapters/console-logger';
 export type { Logger, LoggerLevel } from './ports/logger-port';
 export { default as version } from './version';
+export { default as ForestServerClient, OAuthExchangeError } from './oauth/forest-server-client';
+export type {
+  ServerTokens,
+  RegisteredClient,
+  ExchangeCodeParams,
+} from './oauth/forest-server-client';
+export { default as createOAuthRoutes } from './oauth/oauth-routes';
+export { default as createInMemorySessionStore } from './oauth/session-store';
+export type { SessionStore, StoredSession, CreatedSession } from './oauth/session-store';
+export { default as createTokenCipher } from './oauth/token-cipher';
+export { default as ensureFreshServerAccess } from './oauth/session-lifecycle';
+export { issueBffAccessToken, BFF_ACCESS_TOKEN_TYPE } from './oauth/bff-token';
+export type { BffAccessTokenPayload } from './oauth/bff-token';
+export { createPkcePair } from './oauth/pkce';
+export { OAuthRequestError } from './oauth/oauth-error';

packages/agent-bff/src/oauth/bff-token.ts

@@ -0,0 +1,53 @@
+import type { UserInfo } from '@forestadmin/forestadmin-client';
+
+import jsonwebtoken from 'jsonwebtoken';
+
+export const BFF_ACCESS_TOKEN_TYPE = 'bff_access';
+export const BFF_ACCESS_TOKEN_MAX_EXPIRES_IN = 15 * 60;
+
+export interface IssueBffAccessTokenParams {
+  sid: string;
+  user: UserInfo;
+  renderingId: number;
+  authSecret: string;
+  expiresInSeconds: number;
+}
+
+export interface BffAccessTokenPayload {
+  type: typeof BFF_ACCESS_TOKEN_TYPE;
+  sid: string;
+  id: number;
+  email: string;
+  first_name: string;
+  last_name: string;
+  team: string;
+  rendering_id: string;
+  permission_level: string;
+  tags: Record<string, string>;
+}
+
+export function issueBffAccessToken({
+  sid,
+  user,
+  renderingId,
+  authSecret,
+  expiresInSeconds,
+}: IssueBffAccessTokenParams): string {
+  const payload: BffAccessTokenPayload = {
+    type: BFF_ACCESS_TOKEN_TYPE,
+    sid,
+    id: user.id,
+    email: user.email,
+    first_name: user.firstName,
+    last_name: user.lastName,
+    team: user.team,
+    rendering_id: String(renderingId),
+    permission_level: user.permissionLevel,
+    tags: user.tags ?? {},
+  };
+
+  return jsonwebtoken.sign(payload, authSecret, {
+    algorithm: 'HS256',
+    expiresIn: Math.min(expiresInSeconds, BFF_ACCESS_TOKEN_MAX_EXPIRES_IN),
+  });
+}