Project setup

1. Copy the source/ directory into your project root, e.g. vendor/redwood/.

2. Add path aliases to tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@rwapi/*": ["vendor/redwood/api/src/*"]
    },
    "module": "CommonJS",
    "target": "ES2020",
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

3. Set environment variables needed at runtime:

NODE_ENV=production          # controls logger pretty-printing
REDWOOD_ENV_PREFIX=          # optional prefix for env injection

4. Import directly from the api/src entry point or sub-paths:

import { createLogger, parseAuthorizationHeader, createVerifier } from './vendor/redwood/api/src'

5. The package reads its own package.json for version exports. Ensure the file exists at vendor/redwood/api/package.json with at minimum a version and dependencies["@prisma/client"] field.

Public API

AUTH_PROVIDER_HEADER

export const AUTH_PROVIDER_HEADER: 'auth-provider'

The canonical header name used to identify which auth provider signed a request. Use this constant instead of a magic string when reading the header in middleware or tests.

getAuthProviderHeader

export const getAuthProviderHeader = (
  event: APIGatewayProxyEvent | Request,
): string | undefined

Extracts the auth-provider header value from either a Lambda proxy event or a standard Web API Request. Use this in custom auth middleware to branch on provider type (e.g., "dbAuth", "supabase").

parseAuthorizationCookie

export type AuthorizationCookies = {
  parsedCookie: Record<string, string | undefined>
  rawCookie: string
  type: string | undefined
} | null

export const parseAuthorizationCookie = (
  event: APIGatewayProxyEvent | Request,
): AuthorizationCookies

Parses the Cookie header and extracts the auth provider type embedded inside it. Returns null for unauthenticated requests. Use in cookie-based session auth flows where the JWT is stored in a cookie rather than the Authorization header.

createVerifier

export const createVerifier = (
  type: SupportedVerifierTypes,
  options?: VerifyOptions,
): WebhookVerifier

Factory that returns a WebhookVerifier instance for the specified signature scheme. Supported types include sha256Verifier, sha1Verifier, base64Sha256Verifier, jwtVerifier, and secretKeyVerifier. Use this to verify inbound webhook payloads from third-party services.

formatCacheKey

export const formatCacheKey = (key: CacheKey, prefix?: string): string

Normalizes a string | string[] cache key into a single string, optionally prepending a namespace prefix separated by -. Use before passing keys to any cache client to avoid collision across models or services.

Working examples

Scenario - Verify an incoming GitHub webhook

Your Express route receives a POST from GitHub. Verify the X-Hub-Signature-256 header before processing.

import { createVerifier } from './vendor/redwood/api/src/auth/verifiers'

const verifier = createVerifier('sha256Verifier', {
  signatureHeader: 'X-Hub-Signature-256',
})

app.post('/webhooks/github', async (req, res) => {
  try {
    const body = await req.text()
    const isValid = verifier.verify({
      body,
      signature: req.headers['x-hub-signature-256'] as string,
      secret: process.env.GITHUB_WEBHOOK_SECRET!,
    })
    if (!isValid) return res.status(401).send('Bad signature')
    // process payload
    res.sendStatus(200)
  } catch (e) {
    res.status(400).send((e as Error).message)
  }
})

Scenario - Extract auth provider from a fetch Request

In an edge middleware that receives a Request object, determine which auth provider the client is using.

import {
  getAuthProviderHeader,
  parseAuthorizationCookie,
} from './vendor/redwood/api/src/auth'

export async function middleware(request: Request): Promise<Response> {
  const provider = getAuthProviderHeader(request)

  if (!provider) {
    // fall back to cookie-based auth
    const cookieAuth = parseAuthorizationCookie(request)
    if (!cookieAuth) {
      return new Response('Unauthorized', { status: 401 })
    }
    console.log('Auth via cookie, type:', cookieAuth.type)
  } else {
    console.log('Auth via header, provider:', provider)
  }

  return new Response('OK')
}

Scenario - Cache a Prisma query result with Redis

Wrap an expensive findMany call with a Redis-backed cache using the cache utilities.

import { RedisClient, formatCacheKey } from './vendor/redwood/api/src/cache'
import { createLogger } from './vendor/redwood/api/src/logger'

const logger = createLogger({ name: 'cache-example' })
const redis = new RedisClient(redisConnection, { logger })

async function getProducts(categoryId: number) {
  const key = formatCacheKey(['products', String(categoryId)], 'shop')
  // key => "shop-products-42"

  const cached = await redis.get(key)
  if (cached) return JSON.parse(cached)

  const products = await db.product.findMany({ where: { categoryId } })
  await redis.set(key, JSON.stringify(products), { expires: 300 })
  return products
}

File walkthrough

• api/src/index.ts - Main barrel export; re-exports auth, errors, validations, transforms, CORS, event utilities, and version constants.
• api/src/auth/index.ts - Auth header/cookie parsing utilities and shared constants like AUTH_PROVIDER_HEADER.
• api/src/auth/verifiers/ - Individual webhook signature verifiers (SHA1, SHA256, Base64, JWT, secret key) plus the createVerifier factory.
• api/src/cache/ - Caching abstraction with MemcachedClient, RedisClient, InMemoryClient, key formatting helpers, and timeout error types.
• api/src/logger/index.ts - Pino-based structured logger with Prisma-compatible log level types and environment detection helpers.
• api/src/validations/ - Input validation helpers for service functions.
• api/src/webhooks/ - Higher-level webhook processing helpers built on top of verifiers.
• api/src/cors.ts - CORS header construction utilities.
• api/src/errors.ts - Typed error classes for use across the API layer.
• api/src/event.ts - Normalizes Lambda proxy events and Web Request objects into a unified interface.
• api/src/transforms.ts - Request/response body transformation helpers.
• api/src/types.ts - Shared TypeScript types across the API package.

Common pitfalls and fixes

• require('../package.json') fails at runtime - Ensure vendor/redwood/api/package.json exists and resolveJsonModule: true is set in tsconfig.json.
• aws-lambda types missing - Install @types/aws-lambda as a dev dependency; it is a pure type package not included by default.
• Pino outputs JSON in development and breaks readability - Set NODE_ENV=development and use pino-pretty as a transport: pino({ transport: { target: 'pino-pretty' } }).
• Cache key collisions across environments - Always pass a prefix to formatCacheKey that includes the environment (e.g., prod-users vs staging-users).
• cookie package ESM/CJS mismatch - Pin cookie to ^0.6.0 and ensure your bundler is configured with esModuleInterop: true; v1.x changed the export shape.
• createVerifier throws for unknown type - The type argument must exactly match a key in verifierLookup; check api/src/auth/verifiers/common.ts for the exhaustive list before passing dynamic strings.

Vibe-coding prompt template

I have the RedwoodJS API package source code in `vendor/redwood/` and a usage guide
at `USAGE.md`. I am building a Node.js/TypeScript Express application.

Please help me integrate the following capabilities step-by-step:

1. Set up the logger from `vendor/redwood/api/src/logger` as the global logger for
   my Express app, with Prisma query logging enabled.
2. Add webhook signature verification to my `/webhooks` route using `createVerifier`
   from `vendor/redwood/api/src/auth/verifiers`.
3. Add cookie-based auth provider detection middleware using `parseAuthorizationCookie`
   and `getAuthProviderHeader` from `vendor/redwood/api/src/auth`.
4. Wire up the Redis cache client from `vendor/redwood/api/src/cache` for caching
   database queries, using `formatCacheKey` for all keys.

For each step: show the exact import paths relative to my project root, the code to
add, and any environment variables required. Reference `USAGE.md` for type signatures
and constraints. Do not invent exports that are not documented there.

License and credit

RedwoodJS is released under the MIT License. See source/LICENSE if present, or refer to the upstream repository at https://github.com/redwoodjs/redwood. The upstream package family is redwoodjs/redwood (packages monorepo).

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

NestJS Progressive Node.js Backend Framework

Automation, Utilities & Developer Tools

Free