Developer MessagesClaude MessagesShow Tool Use

jeff

I broke my own naming rule on the config env flag names name when I named them isProduction and isDevelopment etc.
For consistency, clarity, and searchability, we should use the short env names: prod, dev, unit, e2e, and test rather than the long form names.
Here's an example in the cwc-api package.

export type CwcApiConfig = {
  // Environment (derived - skipped in .env generation)
  runtimeEnvironment: RuntimeEnvironment;
  isProduction: boolean;
  isDevelopment: boolean;
  isTest: boolean;
  isUnitTest: boolean;
  isEndToEnd: boolean;
  ...

Let's change those flags, in all packages, to isProd, isDev, isUnit, isE2E, and isTest, and update all places in the code that reference them please.

Claude

I'll explore the codebase to understand the full scope of this renaming task. Let me find all packages with these config flags and all references to them.

Excellent, I have a comprehensive view of all files that need to be updated. Let me write the plan file.

Current Name	New Name
`isProduction`	`isProd`
`isDevelopment`	`isDev`
`isUnitTest`	`isUnit`
`isEndToEnd`	`isE2E`
`isTest`	`isTest` (unchanged)

Package	File
cwc-api	`packages/cwc-api/src/config/config.types.ts`
cwc-storage	`packages/cwc-storage/src/config/config.types.ts`
cwc-sql	`packages/cwc-sql/src/config/config.types.ts`
cwc-auth	`packages/cwc-auth/src/config/config.types.ts`
cwc-backend-utils	`packages/cwc-backend-utils/src/backendUtils.types.ts`

Package	File
cwc-api	`packages/cwc-api/src/config/loadConfig.ts`
cwc-storage	`packages/cwc-storage/src/config/loadConfig.ts`
cwc-sql	`packages/cwc-sql/src/config/loadConfig.ts`
cwc-auth	`packages/cwc-auth/src/config/loadConfig.ts`

I've created a comprehensive plan. The task is straightforward - a consistent rename across all packages. The exploration found all affected files across 6 packages.

Summary of changes:

5 type definition files - Update the config type definitions
4 loadConfig files - Update variable declarations and assignments
15+ usage sites - Update config.isProduction → config.isProd, etc.
7+ test files - Update assertions, test titles, and mock configs
1 configuration helper - Update the hardcoded derived properties list
1 documentation file - Update CLAUDE.md naming convention table

The implementation will follow this order: types first → loadConfig → usages → tests → documentation.

Exited plan mode

Plan approved

I'll start implementing the rename. Let me create a todo list to track progress.

Let me read all the type definition files first.

Now I'll update all 5 type definition files.

Type definitions updated. Now let me read the loadConfig files.

Now I'll update all 4 loadConfig files.

LoadConfig files updated. Now let me update the usage sites starting with cwc-api.

Now I'll update the cwc-api usage sites.

cwc-api done. Now let me update cwc-storage usage sites.

Now I'll update cwc-storage usage sites.

Now let me read and update cwc-sql usage sites.

Now I'll update cwc-sql usage sites.

Now let me read and update cwc-auth usage sites. This package has many files with these references.

I'll update the cwc-auth files. Let me use replace_all for the repeated occurrences.

Now let me update the remaining cwc-auth handler files.

Now let me update cwc-backend-utils.

Now let me update cwc-configuration-helper.

Let me also update the CLAUDE.md in cwc-configuration-helper.

Now let me update the test files.

Let me update the test files. I'll start with the config.mock.ts files.

Now let me update the config.test.ts file.

Now let me update the test titles in QueryHandler.test.ts and MutationHandler.test.ts.

Now let me read and update the remaining test files in cwc-sql and cwc-auth.

Now let me read and update the cwc-auth test files.

Now let me update the CLAUDE.md documentation.

Let me also check the package-specific CLAUDE.md files for any references that need updating.

Documentation is updated. Now let me run typecheck and tests.

Typecheck passed. Now let me run the tests.

There are test failures in cwc-auth. Let me check what's happening - these tests expect isDev to be true but are running in unit mode. Let me read the test file.

I see the issue. The tests expect development-mode behavior but createMockConfig() returns unit config where isDev: false. I need to add a dev config function to the cwc-auth mocks.

I need to add a createDevConfig function and update the tests that expect dev-mode behavior.

Now let me update the mocks index file to export the new function.

System

Claude

I need to update the auth.test.ts file to use createDevConfig() for tests that expect dev-mode behavior. Let me read that file first.

Now I can see the issue. These tests expect dev-mode behavior but are using createMockConfig() which returns unit config with isDev: false. I need to update them to use createDevConfig().

Now I'll update each test that expects dev-mode behavior to use createDevConfig().

Now let me re-run the cwc-auth tests to verify the fixes.

Good progress - the original auth.test.ts failures are mostly fixed. There are additional failures in handlers.test.ts and workers.test.ts that need the same fix. Let me read and update those.

Now I'll fix both files. Let me update handlers.test.ts first.

Now let me fix workers.test.ts.

Finally, I need to fix the remaining auth.test.ts failure for the MISSING_CREDENTIALS test.

Now let me re-run the cwc-auth tests to verify all fixes are working.

All cwc-auth tests pass. Let me run the full typecheck and test suite to verify everything is working.

All typechecks and tests pass. Let me update the todo list to mark the task as complete.

The environment config flag rename is complete. All typechecks and tests pass.

Summary of changes:

Type Definitions (5 files):

Renamed isProduction → isProd, isDevelopment → isDev, isUnitTest → isUnit, isEndToEnd → isE2E in config types across cwc-api, cwc-storage, cwc-sql, cwc-auth, and cwc-backend-utils

loadConfig Functions (4 files):

Updated variable names in cwc-api, cwc-storage, cwc-sql, and cwc-auth

Usage Sites (6 packages):

Updated all references in cwc-api, cwc-storage, cwc-sql, cwc-auth, cwc-backend-utils, and cwc-configuration-helper

Test Files:

Updated mock config factories (added createDevConfig() to cwc-auth mocks)
Updated tests that expect dev-mode behavior to use createDevConfig() instead of createMockConfig()
Tests requiring dev-mode behavior (detailed error codes like USER_NOT_FOUND, INVALID_PASSWORD) now correctly use dev config

Documentation:

Updated root CLAUDE.md 1-to-1 Naming Convention table
Updated package-level CLAUDE.md files with new flag names

jeff

I'm seeing inconsistencies in the code related to how we refer to the cwc-secrets folder.
That folder is located at /Users/jeffbazinet/coding-with-claude/private/cwc-secrets
It looks like some places in the code are missing the private folder.
Can you help me straighten this out?
I would like to define that string once, maybe in cwc-types unless you have a better idea, and import it into the other packages.
I would rather define it as ~/coding-with-claude/private/cwc-secrets but is there a reason to use the fully qualified path /Users/jeffbazinet/coding-with-claude/private/cwc-secrets?
Note: this path only gets used when running the applications locally.
Please let me know if you find any similar path related issues, thanks!

Claude

I'll help you clean up the cwc-secrets path references. Let me first read the existing plan file, then explore the codebase to understand the current state of these path references.

This is a different task from the previous plan. Let me explore the codebase to find all references to cwc-secrets paths and understand the current patterns.

This is very helpful. Let me read the SqlClientKeysUtil.ts file to understand the current implementation and verify the inconsistency.

I found a clear inconsistency. In SqlClientKeysUtil.ts line 43, the path uses ../../../cwc-secrets/sql-client-api-keys (3 levels, no private/), while loadDotEnv.ts correctly uses ../../../../private/cwc-secrets/env/ (4 levels, with private/).

Before I design the plan, I have some clarifying questions:

Claude is asking...

LocationWhere should the shared secrets path constant be defined?

cwc-backend-utils- Best fit - already Node.js-specific, contains loadDotEnv and SqlClientKeysUtil

cwc-types- You suggested this, but cwc-types is browser+Node.js compatible and this needs Node.js os.homedir()

Path styleThe `~` symbol only works in shells, not in Node.js. Should I use `os.homedir()` to get the home directory and construct an absolute path?

Yes, use os.homedir()- Creates ~/coding-with-claude/private/cwc-secrets as an absolute path using Node.js os module

Keep relative paths- Continue using ../../../../private/cwc-secrets relative to package directory

DesignHow should the constant be structured?

Single base path constant- Define LOCAL_SECRETS_PATH = ~/coding-with-claude/private/cwc-secrets, construct subdirs from it

Multiple path constants- Define separate constants for ENV_PATH, SQL_KEYS_PATH, DEPLOYMENT_PATH, etc.

Developer Response

Q: Where should the shared secrets path constant be defined?

A: "cwc-backend-utils"

Q: The `~` symbol only works in shells, not in Node.js. Should I use `os.homedir()` to get the home directory and construct an absolute path?

A: "Yes, use os.homedir()"

Q: How should the constant be structured?

A: "Multiple path constants"

Now I have clarity. Let me design the implementation plan.

Excellent design. Let me write the final plan to the plan file.

Action	File
Create	`packages/cwc-backend-utils/src/localSecretsPaths.ts`
Update	`packages/cwc-backend-utils/src/loadDotEnv.ts`
Update	`packages/cwc-backend-utils/src/SqlClientKeysUtil.ts`
Update	`packages/cwc-backend-utils/src/index.ts`
Update	`packages/cwc-backend-utils/CLAUDE.md`

The plan is ready. Here's a summary:

Problem Found:

SqlClientKeysUtil.ts has a bug: path uses ../../../cwc-secrets/sql-client-api-keys but should be ../../../../private/cwc-secrets/sql-client-api-keys (missing private/ folder and one level)

Solution:

Create localSecretsPaths.ts with path constants using os.homedir():
- LOCAL_SECRETS_BASE_PATH - Base path to cwc-secrets
- LOCAL_SECRETS_ENV_PATH - For .env files
- LOCAL_SECRETS_SQL_KEYS_PATH - For SQL client keys
- LOCAL_SECRETS_CONFIG_HELPER_PATH - For config helper files
- LOCAL_SECRETS_DEPLOYMENT_PATH - For deployment configs
- getLocalEnvFilePath() - Helper function for .env file paths
Update loadDotEnv.ts and SqlClientKeysUtil.ts to use these constants
Update documentation

Exited plan mode

Work interrupted

Are you certain that constants with os.homedir() will work, or should we define functinos for these values?

Good question! Let me verify this works correctly.

Yes, constants with os.homedir() work correctly. The expression is evaluated once when the module is first imported, and the resulting string is stored as the constant value.

Both approaches work:

Approach	Pros	Cons
Constants	Simple, efficient (computed once), cleaner import syntax	Harder to mock in tests
Functions	Easier to mock, lazy evaluation	Slightly more verbose, recomputes each call

Since these paths are only used at application startup (when loadDotEnv and SqlClientKeysUtil are initialized), performance is not a concern.

Claude is asking...

DesignWhich approach do you prefer for the path definitions?

Constants (recommended)- Simpler syntax: LOCAL_SECRETS_SQL_KEYS_PATH. Computed once at import. This is the standard pattern.

Functions- More verbose: getLocalSecretsSqlKeysPath(). Easier to mock if needed for testing.

Developer Response

Q: Which approach do you prefer for the path definitions?

A: "let's do functions but use these names: getSecretsSqlClientApiKeysPath, getSecretsPath, getSecretsEnvPath, getSecretsConfigHelperPath, getSecretsDeploymentPath"

Got it. Let me update the plan with functions using your naming convention.

Action	File
Create	`packages/cwc-backend-utils/src/localSecretsPaths.ts`
Update	`packages/cwc-backend-utils/src/loadDotEnv.ts`
Update	`packages/cwc-backend-utils/src/SqlClientKeysUtil.ts`
Update	`packages/cwc-backend-utils/src/index.ts`
Update	`packages/cwc-backend-utils/CLAUDE.md`

Plan updated with your preferred function naming:

getSecretsPath() - base path
getSecretsEnvPath() - env subdirectory
getSecretsSqlClientApiKeysPath() - SQL client keys
getSecretsConfigHelperPath() - config helper
getSecretsDeploymentPath() - deployment configs
getSecretsEnvFilePath(environment, serviceName) - helper for .env file paths

Exited plan mode

Plan approved

Let me set up the todo list and start implementing.

Now let me update SqlClientKeysUtil.ts.

Typecheck passed. Let me run the full typecheck across all packages to ensure nothing is broken.

All typechecks pass. Let me also run the tests to ensure the changes work correctly.

All tests pass. Let me mark the task as complete.

Implementation complete. Here's a summary of what was done:

Created:

packages/cwc-backend-utils/src/localSecretsPaths.ts - New file with path functions

Updated:

packages/cwc-backend-utils/src/loadDotEnv.ts - Now uses getSecretsEnvFilePath()
packages/cwc-backend-utils/src/SqlClientKeysUtil.ts - Fixed bug and now uses getSecretsSqlClientApiKeysPath()
packages/cwc-backend-utils/src/index.ts - Added export for new module
packages/cwc-backend-utils/CLAUDE.md - Added documentation for new path functions

Bug Fixed:

SqlClientKeysUtil.ts was using ../../../cwc-secrets/sql-client-api-keys (missing private/ and one ../ level)
Now correctly uses getSecretsSqlClientApiKeysPath() which resolves to ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys

New Functions Available:

Function	Returns
`getSecretsPath()`	`~/coding-with-claude/private/cwc-secrets`
`getSecretsEnvPath()`	`{base}/env`
`getSecretsSqlClientApiKeysPath()`	`{base}/sql-client-api-keys`
`getSecretsConfigHelperPath()`	`{base}/configuration-helper`
`getSecretsDeploymentPath()`	`{base}/deployment`
`getSecretsEnvFilePath(env, service)`	`{base}/env/{env}.{service}.env`

All typechecks and tests pass.

jeff

I see even more room for improvement for the getSecrets functions -- if you agree.
const keyPath = runningLocally ? getSecretsSqlClientApiKeysPath() : './sql-client-api-keys';
could be:
const keyPath = getSecretsSqlClientApiKeysPath(runningLocally);
What do you think?

Claude

I agree - that's a cleaner API. It encapsulates the "local vs server" decision inside the function rather than at every call site.

There's one consideration: the server paths follow different patterns for different resources:

SQL keys: ./sql-client-api-keys
Env files: .env.{environment} (different filename pattern, not just different base path)

So for SQL keys it works cleanly, but for env files the server pattern is fundamentally different.

I'd suggest:

For paths with consistent patterns (SQL keys, config helper, deployment): Add the runningLocally parameter
For env files: Keep getSecretsEnvFilePath() as local-only since the server pattern is different

Want me to update the implementation?

// SQL keys, config helper, deployment paths
export function getSecretsSqlClientApiKeysPath(runningLocally: boolean): string {
  return runningLocally 
    ? path.join(getSecretsPath(), 'sql-client-api-keys')
    : './sql-client-api-keys';
}

// Env files stay local-only (server uses different pattern)
export function getSecretsEnvFilePath(
  environment: RuntimeEnvironment,
  serviceName: BackendServiceName
): string {
  return path.join(getSecretsEnvPath(), `${environment}.${serviceName}.env`);
}

jeff

Claude

Write

{
  "file_path": "/Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-backend-utils/src/localSecretsPaths.ts",
  "content": "'use strict';\n\n/**\n * Secrets path functions for local and server environments\n *\n * IMPORTANT: These functions handle both local (dev/unit/e2e) and server (test/prod) paths.\n * Pass `runningLocally` to get the appropriate path for the environment.\n *\n * Directory structure (local):\n * ~/coding-with-claude/private/cwc-secrets/\n *   ├── env/                          # Environment files\n *   │   ├── dev.cwc-api.env\n *   │   ├── dev.cwc-auth.env\n *   │   ├── unit.cwc-api.env\n *   │   └── ...\n *   ├── sql-client-api-keys/          # SQL client JWT keys\n *   │   ├── sql-client-api-key-private.pem\n *   │   └── sql-client-api-key-public.pem\n *   ├── configuration-helper/         # Deployment secrets (JSON)\n *   └── deployment/                   # Deployment configs\n *       ├── servers.json\n *       └── ssh-keys/\n */\n\nimport os from 'node:os';\nimport path from 'node:path';\nimport type { RuntimeEnvironment } from 'cwc-types';\nimport type { BackendServiceName } from './backendUtils.types';\n\n/**\n * Base path to the cwc-secrets directory for local development\n * @returns ~/coding-with-claude/private/cwc-secrets\n */\nexport function getSecretsPath(): string {\n  return path.join(os.homedir(), 'coding-with-claude/private/cwc-secrets');\n}\n\n/**\n * Path to the environment files directory (local only)\n * @returns ~/coding-with-claude/private/cwc-secrets/env\n */\nexport function getSecretsEnvPath(): string {\n  return path.join(getSecretsPath(), 'env');\n}\n\n/**\n * Path to the SQL client API keys directory\n * @param runningLocally - true for dev/unit/e2e, false for test/prod\n * @returns Local: ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys\n *          Server: ./sql-client-api-keys\n */\nexport function getSecretsSqlClientApiKeysPath(runningLocally: boolean): string {\n  return runningLocally\n    ? path.join(getSecretsPath(), 'sql-client-api-keys')\n    : './sql-client-api-keys';\n}\n\n/**\n * Path to the configuration helper directory\n * @param runningLocally - true for dev/unit/e2e, false for test/prod\n * @returns Local: ~/coding-with-claude/private/cwc-secrets/configuration-helper\n *          Server: ./configuration-helper\n */\nexport function getSecretsConfigHelperPath(runningLocally: boolean): string {\n  return runningLocally\n    ? path.join(getSecretsPath(), 'configuration-helper')\n    : './configuration-helper';\n}\n\n/**\n * Path to the deployment configuration directory\n * @param runningLocally - true for dev/unit/e2e, false for test/prod\n * @returns Local: ~/coding-with-claude/private/cwc-secrets/deployment\n *          Server: ./deployment\n */\nexport function getSecretsDeploymentPath(runningLocally: boolean): string {\n  return runningLocally\n    ? path.join(getSecretsPath(), 'deployment')\n    : './deployment';\n}\n\n/**\n * Constructs the full path to an environment file for local development\n *\n * Note: Server deployments use a different pattern (.env.{environment})\n * so this function is only for local environments.\n *\n * @param environment - The runtime environment (dev, unit, e2e)\n * @param serviceName - The backend service name\n * @returns Full absolute path to the .env file\n *\n * @example\n * getSecretsEnvFilePath('dev', 'cwc-api')\n * // Returns: /Users/.../coding-with-claude/private/cwc-secrets/env/dev.cwc-api.env\n */\nexport function getSecretsEnvFilePath(\n  environment: RuntimeEnvironment,\n  serviceName: BackendServiceName\n): string {\n  return path.join(getSecretsEnvPath(), `${environment}.${serviceName}.env`);\n}\n"
}

Tool Result

The file /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/cwc-backend-utils/src/localSecretsPaths.ts has been updated. Here's the result of running `cat -n` on a snippet of the edited file:
     1→'use strict';
     2→
     3→/**
     4→ * Secrets path functions for local and server environments
     5→ *
     6→ * IMPORTANT: These functions handle both local (dev/unit/e2e) and server (test/prod) paths.
     7→ * Pass `runningLocally` to get the appropriate path for the environment.
     8→ *
     9→ * Directory structure (local):
    10→ * ~/coding-with-claude/private/cwc-secrets/
    11→ *   ├── env/                          # Environment files
    12→ *   │   ├── dev.cwc-api.env
    13→ *   │   ├── dev.cwc-auth.env
    14→ *   │   ├── unit.cwc-api.env
    15→ *   │   └── ...
    16→ *   ├── sql-client-api-keys/          # SQL client JWT keys
    17→ *   │   ├── sql-client-api-key-private.pem
    18→ *   │   └── sql-client-api-key-public.pem
    19→ *   ├── configuration-helper/         # Deployment secrets (JSON)
    20→ *   └── deployment/                   # Deployment configs
    21→ *       ├── servers.json
    22→ *       └── ssh-keys/
    23→ */
    24→
    25→import os from 'node:os';
    26→import path from 'node:path';
    27→import type { RuntimeEnvironment } from 'cwc-types';
    28→import type { BackendServiceName } from './backendUtils.types';
    29→
    30→/**
    31→ * Base path to the cwc-secrets directory for local development
    32→ * @returns ~/coding-with-claude/private/cwc-secrets
    33→ */
    34→export function getSecretsPath(): string {
    35→  return path.join(os.homedir(), 'coding-with-claude/private/cwc-secrets');
    36→}
    37→
    38→/**
    39→ * Path to the environment files directory (local only)
    40→ * @returns ~/coding-with-claude/private/cwc-secrets/env
    41→ */
    42→export function getSecretsEnvPath(): string {
    43→  return path.join(getSecretsPath(), 'env');
    44→}
    45→
    46→/**
    47→ * Path to the SQL client API keys directory
    48→ * @param runningLocally - true for dev/unit/e2e, false for test/prod
    49→ * @returns Local: ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys
    50→ *          Server: ./sql-client-api-keys
    51→ */
    52→export function getSecretsSqlClientApiKeysPath(runningLocally: boolean): string {
    53→  return runningLocally
    54→    ? path.join(getSecretsPath(), 'sql-client-api-keys')
    55→    : './sql-client-api-keys';
    56→}
    57→
    58→/**
    59→ * Path to the configuration helper directory
    60→ * @param runningLocally - true for dev/unit/e2e, false for test/prod
    61→ * @returns Local: ~/coding-with-claude/private/cwc-secrets/configuration-helper
    62→ *          Server: ./configuration-helper
    63→ */
    64→export function getSecretsConfigHelperPath(runningLocally: boolean): string {
    65→  return runningLocally
    66→    ? path.join(getSecretsPath(), 'configuration-helper')
    67→    : './configuration-helper';
    68→}
    69→
    70→/**
    71→ * Path to the deployment configuration directory
    72→ * @param runningLocally - true for dev/unit/e2e, false for test/prod
    73→ * @returns Local: ~/coding-with-claude/private/cwc-secrets/deployment
    74→ *          Server: ./deployment
    75→ */
    76→export function getSecretsDeploymentPath(runningLocally: boolean): string {
    77→  return runningLocally
    78→    ? path.join(getSecretsPath(), 'deployment')
    79→    : './deployment';
    80→}
    81→
    82→/**
    83→ * Constructs the full path to an environment file for local development
    84→ *
    85→ * Note: Server deployments use a different pattern (.env.{environment})
    86→ * so this function is only for local environments.
    87→ *
    88→ * @param environment - The runtime environment (dev, unit, e2e)
    89→ * @param serviceName - The backend service name
    90→ * @returns Full absolute path to the .env file
    91→ *
    92→ * @example
    93→ * getSecretsEnvFilePath('dev', 'cwc-api')
    94→ * // Returns: /Users/.../coding-with-claude/private/cwc-secrets/env/dev.cwc-api.env
    95→ */
    96→export function getSecretsEnvFilePath(
    97→  environment: RuntimeEnvironment,
    98→  serviceName: BackendServiceName
    99→): string {
   100→  return path.join(getSecretsEnvPath(), `${environment}.${serviceName}.env`);
   101→}
   102→

System

Claude

I'll continue by updating SqlClientKeysUtil.ts to use the new function signature, then update CLAUDE.md and run typecheck.

Now let me update CLAUDE.md to reflect the updated function signatures.

Now let me run typecheck to verify the changes compile correctly.

Let me also check if any other packages use these functions to ensure they still compile.

The functions are only used within cwc-backend-utils currently. Let me run a broader typecheck to verify the entire project compiles.

All packages typecheck successfully. Here's a summary of the completed changes:

Updated Files:

localSecretsPaths.ts - Added runningLocally parameter to encapsulate local vs server path logic:
- getSecretsSqlClientApiKeysPath(runningLocally) - returns local or server path
- getSecretsConfigHelperPath(runningLocally) - returns local or server path
- getSecretsDeploymentPath(runningLocally) - returns local or server path

SqlClientKeysUtil.ts - Simplified to use the new function signature:

// Before:
const keyPath = runningLocally ? getSecretsSqlClientApiKeysPath() : './sql-client-api-keys';

// After:
const keyPath = getSecretsSqlClientApiKeysPath(runningLocally);

CLAUDE.md - Updated documentation to reflect the new function signatures with the runningLocally parameter and both local/server return values.

The path logic is now fully encapsulated within the localSecretsPaths.ts functions, making the call sites cleaner and more maintainable.

jeff

I think that we can pass runningLocally into the getSecretsEnvFilePath function as well.

const envPath = runningLocally
    ? getSecretsEnvFilePath(environment, serviceName)
    : resolve(process.cwd(), `.env.${environment}`);

becomes

const envPath = getSecretsEnvFilePath(runningLocally, environment, serviceName)

Claude

Good catch - let's apply the same pattern to getSecretsEnvFilePath for consistency.

Let me try a workaround approach.

Now let me update loadDotEnv.ts to use the new signature.

Now let me update CLAUDE.md to reflect the updated getSecretsEnvFilePath signature.

Now let me run typecheck to verify everything compiles.

All packages typecheck successfully. Here's the summary of this update:

Updated getSecretsEnvFilePath to follow the same pattern:

// Before:
const envPath = runningLocally
  ? getSecretsEnvFilePath(environment, serviceName)
  : resolve(process.cwd(), `.env.${environment}`);

// After:
const envPath = getSecretsEnvFilePath(runningLocally, environment, serviceName);

Files modified:

localSecretsPaths.ts - Added runningLocally as first parameter to getSecretsEnvFilePath()
loadDotEnv.ts - Updated to use new signature, removed unused resolve import
CLAUDE.md - Updated function table and usage example

All path functions that need to handle both local and server environments now consistently use the runningLocally parameter pattern.

jeff

quick question: every time we make a change, several tsconfig.buildinfo files are updated. should these files be included in the github code repository or can I gitignore them?

Claude

These files should be gitignored. They are build cache artifacts, not source code.

*.tsbuildinfo files are generated by TypeScript's incremental compilation (composite: true in tsconfig). They store metadata about the previous build to speed up subsequent compiles.

Why to gitignore them:

Machine-specific build cache (like node_modules or dist)
Regenerated on every build
Cause unnecessary merge conflicts
Different developers' machines may produce different content

Add this to your .gitignore:

*.tsbuildinfo

jeff

yes please!

Claude

Done. If you have any *.tsbuildinfo files already tracked by git, you can remove them from tracking with:

git rm --cached '**/*.tsbuildinfo'

jeff

I should delete them and push that change in the PR, since they are already in the github repo, right?

Claude

Yes, exactly. Adding to .gitignore only prevents future tracking - files already in the repo stay there until explicitly removed.

Run this to remove them from git (they'll regenerate locally on next build):

git rm --cached '**/*.tsbuildinfo'

Then commit that deletion along with the .gitignore update in your PR. After that, they'll be gone from the repo and ignored going forward.

jeff

This has been a nice code cleanup session - thank you!

Claude

You're welcome! Good progress today:

Consolidated secrets path logic with runningLocally parameter across all path functions
Simplified call sites in SqlClientKeysUtil.ts and loadDotEnv.ts
Added *.tsbuildinfo to .gitignore

Clean, consistent code that's easier to maintain. Have a good one!

Session 22: rename config env flags

48 files modified

.gitignore

node_modules
dist/
.DS_Store
coverage/
.env
.env.*
*.env
ai-session-transcripts/
temp-files/
transcripts/

# TypeScript
*.tsbuildinfo

# Turborepo
.turbo/

# pnpm
.pnpm-store/
.pnpm-debug.log

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

CRITICAL: Role and Professional Standards

Claude Code's role on this project is to serve as a "highly experienced senior software engineer and application architect" with "in-depth understanding of the CWC codebase, conventions, and rules."

It is assumed, and imperative, that as a senior engineer, you will do your due diligence:

Required Due Diligence for Every Task

Before proposing any design, architecture, or implementation:

Read all relevant package CLAUDE.md files
- If touching database → read packages/cwc-database/CLAUDE.md
- If defining/modifying types → read packages/cwc-types/CLAUDE.md
- If working with any package → read that package's CLAUDE.md file
- Package-specific conventions MUST be followed
Examine existing code in all affected packages
- Check for existing types, schemas, or utilities before proposing new ones
- Understand established patterns and conventions
- Identify dependencies between packages
Understand the full scope
- Identify all packages affected by the feature or change
- Consider both direct changes and indirect impacts (shared types, utilities, etc.)
- Plan across package boundaries, not in isolation

Cross-Package Feature Planning

When working on features that span multiple packages:

Discovery phase first - Survey the landscape before designing
Read documentation - All relevant package CLAUDE.md files
Examine existing implementations - Check for related code/patterns
Design within constraints - Follow established conventions
Present context with design - Show what you reviewed and how your design follows patterns

This is not optional. The developer should not have to repeatedly point out missed conventions or overlooked existing code. Professional engineers build on institutional knowledge rather than reinventing or contradicting established patterns.

Package-Specific Documentation

Claude Code automatically loads all CLAUDE.md files recursively. When working in a specific package or on package-specific tasks, refer to these package documentation files for detailed guidance:

cwc-types → packages/cwc-types/CLAUDE.md
- Type generation from database schema
- Entity type patterns (Strict Base + Partial)
- Union type naming conventions
- Request-scoped caching patterns
cwc-database → packages/cwc-database/CLAUDE.md
- Database schema conventions
- Table/index/view naming patterns
- Migration script patterns
- Database design patterns (JWT tables, multi-step processes, etc.)
cwc-deployment → packages/cwc-deployment/CLAUDE.md
- Deployment system architecture
- SSH-based deployment workflows
- Docker container management
- Troubleshooting and error handling
cwc-schema → packages/cwc-schema/CLAUDE.md
- Schema definition patterns
- Runtime validation functions
- Hybrid validation with Zod
- Column type definitions
cwc-utils → packages/cwc-utils/CLAUDE.md
- Shared utilities (browser + Node.js)
- Profanity checking and content filtering
- Cross-platform compatibility guidelines
- Adding new utilities

Project Overview

What is codingwithclaude?

A multi-tenant developer publishing platform: a dynamic, real-time publishing platform that serves as both a public feed for developer content and a private dashboard for external developers (users of the app) to manage and publish their own technical blog posts, organized by "Projects."

Project name & aliases

In this document and prompts from the developer, all of these names or phrases are assumed to refer to the project:

coding-with-claude-application
codingwithclaude
coding-with-claude
CWC or cwc

Proactive Documentation Philosophy

CRITICAL: This file is a living knowledge base that must be continuously updated.

As Claude Code works with the developer, it is EXPECTED to proactively capture all learnings, patterns, critical instructions, and feedback in this CLAUDE.md file WITHOUT being reminded. This is a professional partnership where:

Every gap discovered during planning or analysis → Document the pattern to prevent future occurrences
Every critical instruction from the developer → Add to relevant sections immediately
Every "I forgot to do X" moment → Create a checklist or rule to prevent repetition
Every architectural pattern learned → Document it for consistency
Every planning session insight → Capture the learning before implementation begins

When to update CLAUDE.md:

DURING planning sessions - This is where most learning happens through analysis, feedback, and corrections
After receiving critical feedback - Document the expectation immediately
After discovering a bug or oversight - Add checks/rules to prevent it
After analysis reveals gaps - Document what to check in the future
When the developer explains "this is how we do X" - Add it to the guide
After implementing a new feature - Capture any additional patterns discovered during execution

Planning sessions are especially critical: The analysis, feedback, and corrections that happen during planning contain the most valuable learnings. Update CLAUDE.md with these insights BEFORE starting implementation, not after.

Professional expectation: The developer should not need to repeatedly point out the same oversights or remind Claude Code to document learnings. Like professional teammates, we learn from each interaction and build institutional knowledge.

Format: When updating this file, maintain clear structure, provide code examples where helpful, and organize related concepts together. Focus exclusively on information that helps Claude Code operate effectively during AI-assisted coding sessions.

Package-Specific Documentation: When learning package-specific patterns, update the appropriate package CLAUDE.md file, not this root file.

CLAUDE.md File Specification

Purpose: CLAUDE.md files are memory files for AI assistants (like Claude Code), NOT documentation for human developers.

What CLAUDE.md IS for:

Architectural patterns and critical design decisions
Code conventions, naming rules, and style preferences
What to check during planning sessions
Lessons learned and mistakes to avoid
Project-specific security rules and compliance requirements
Critical implementation patterns that must be followed
"If you see X, always do Y" type rules
Checklists for common operations

What CLAUDE.md is NOT for (belongs in README.md):

API documentation and endpoint specifications
Usage examples and tutorials for humans
Setup and installation instructions
General explanations and marketing copy
Step-by-step guides and how-tos
Detailed configuration walkthroughs
Complete type definitions (already in code)
Performance tuning guides for users

File Size Targets:

Warning threshold: 40,000 characters per file (Claude Code performance degrades)
Recommended: Keep under 500 lines when possible for fast loading
Best practice: If a package CLAUDE.md approaches 300-400 lines, review for README-style content
For large packages: Use concise bullet points; move examples to README

Content Guidelines:

Be specific and actionable: "Use 2-space indentation" not "Format code properly"
Focus on patterns: Show the pattern, explain when to use it
Include context for decisions: Why this approach, not alternatives
Use code examples sparingly: Only when pattern is complex
Keep it scannable: Bullet points and clear headers

CLAUDE.md vs README.md:

CLAUDE.md	README.md
For AI assistants	For human developers
Patterns and rules	Complete documentation
What to check/avoid	How to use and setup
Concise and focused	Comprehensive and detailed
Loaded on every session	Read when needed

Documentation Organization in Monorepos

Critical learnings about Claude Code documentation structure:

Claude Code automatically loads all CLAUDE.md files recursively:
- Reads CLAUDE.md in current working directory
- Recurses upward to parent directories (stops at workspace root)
- Discovers nested CLAUDE.md files in subdirectories
- All files are loaded together - they complement, not replace each other
Package-specific CLAUDE.md is the standard pattern for monorepos:
- Root CLAUDE.md contains monorepo-wide conventions (tooling, git workflow, shared patterns)
- Package CLAUDE.md contains package-specific patterns (database schema, deployment, type generation)
- Working from any directory loads both root and relevant package docs automatically
Performance limit: 40,000 characters per file:
- Claude Code shows performance warning when CLAUDE.md exceeds 40k characters
- Solution: Split into package-specific files, not multiple files in .claude/ directory
- Only CLAUDE.md files are automatically loaded; other .md files in .claude/ are NOT
Optimize for AI-assisted coding, not human readers:
- Include patterns, conventions, code examples, and strict rules
- Include "what to check during planning" and "lessons learned" sections
- Exclude content primarily for human developers (marketing copy, general explanations)
- Focus on actionable information needed during coding sessions

When to create package CLAUDE.md:

Package has unique architectural patterns
Package has specific conventions (schema rules, deployment procedures)
Package has domain-specific knowledge (auth flows, type generation)
Package documentation would exceed ~500 lines in root file

File Access Restrictions and Security Boundaries

Claude Code operates under strict file access restrictions to protect sensitive data:

Workspace Boundaries

Claude Code can ONLY access files within the monorepo root: ./coding-with-claude-application
No access to parent directories, system files, or files outside this workspace
This is enforced by Claude Code's security model

Prohibited File Access

Claude Code is explicitly blocked from reading or writing:

Environment files:
- .env files at any location
- .env.* files (e.g., .env.local, .env.production, .env.dev)
- *.env files (e.g., prod.cwc-sql.env, dev.cwc-storage.env, test.cwc-app.env)
- Any variation of environment configuration files
Secret and credential files:
- Any directory named secrets/, secret/, or private/
- Any directory with secret, secrets, or private in its path
- Any file with secret, secrets, private, or credentials in its filename
- Service account JSON files (service-account-*.json)
- Firebase configuration files (google-services.json, GoogleService-Info.plist)
- Any file matching *credentials*.json
Rationale:
- Prevents accidental exposure of API keys, database passwords, and authentication tokens
- Protects production credentials and service account keys
- Reduces risk of sensitive data being included in code examples or logs
- Enforces principle of least privilege

These restrictions are enforced in .claude/settings.json and cannot be overridden during a session.

Git Workflow

The developer handles all git operations manually. Claude should:

Never initiate git commits, pushes, pulls, or any write operations
Only use git for read-only informational purposes (status, diff, log, show)
Not proactively suggest git operations unless explicitly asked

Git write operations are blocked in .claude/settings.json to enforce this workflow.

Architecture Overview

Monorepo Structure (future plan)

root project: /coding-with-claude-application
packages (apps, microservices, utilities):
- cwc-types: shared TypeScript types to be used in all other packages
- cwc-utils: shared utilities for browser and Node.js (profanity checking, validation helpers, etc.)
- cwc-deployment: custom deployment CLI for SSH-based deployment to remote servers
- cwc-backend-utils: shared Node.js utilities that backend/api packages will consume
- cwc-website: public frontend end web application
- cwc-auth: authentication microservice, providing login, logout, signup, password reset, etc.
- cwc-api: the main data api used by cwc-website to read & write data, enforce auth, role-based access policies, and business rules/logic
- cwc-dashboard: an administrative web dashboard app for site owners to manage the app & data
- cwc-admin-api: the admin and data api used by the cwc-dashboard app
- cwc-database: database scripts to create tables, indexes, views, as well as insert configuration data
- cwc-schema: shared schema management library that may be used by frontend and backend packages
- cwc-sql: the only backend service that interacts directly with the database server, uses schema to dynamically generate sql statements
- cwc-e2e: a set of end-to-end tests

Tech Stack: to be determined as we build each package, update this documentation as we go.

Development Tooling & Infrastructure

Monorepo Management

pnpm v9.x + Turborepo v2.x

pnpm workspaces for package management and dependency resolution
- Configured in pnpm-workspace.yaml
- Packages located in packages/*
- Uses content-addressable storage for disk efficiency
- Strict dependency resolution prevents phantom dependencies
Turborepo for task orchestration and caching
- Configured in turbo.json
- Intelligent parallel execution based on dependency graph
- Local caching for faster rebuilds
- Pipeline tasks: build, dev, test, lint, typecheck

Node.js Version

Node.js 22 LTS (specified in .nvmrc)
Required for all development and production environments
Use nvm for version management

Code Quality Tools

TypeScript v5.4+

Configured in tsconfig.base.json
Strict mode enabled with enhanced type checking
JavaScript explicitly disallowed (allowJs: false)
Monorepo-optimized with composite projects
Individual packages extend base config

Module Resolution: bundler

Uses "moduleResolution": "bundler" in tsconfig.base.json
Uses "module": "ES2022" (required for bundler resolution)
Allows clean TypeScript imports without .js extensions
- ✅ Correct: import { Schema } from './types'
- ❌ Not needed: import { Schema } from './types.js'
Still produces correct ES module output in compiled JavaScript
Designed for TypeScript projects compiled by tsc or bundlers

Why bundler over NodeNext:

Better DX: No .js extensions in TypeScript source files
Modern standard: Industry standard for TypeScript libraries and monorepos
Same output: Still generates proper ES modules (.js files)
No trade-offs: Type safety and module compatibility maintained

Note: Previously used "moduleResolution": "NodeNext" which required .js extensions per ES modules spec (e.g., import './types.js'). Switched to bundler in session 007 for cleaner imports across all packages.

ESLint v8.x with TypeScript

Configured in .eslintrc.json
Uses @typescript-eslint/strict ruleset
Enforces explicit function return types
Prohibits any type and non-null assertions
Strict boolean expressions required

Prettier v3.x

Configured in .prettierrc.json
Standards:
- Single quotes
- 2-space indentation
- 100 character line width
- Trailing commas (ES5)
- LF line endings

Root Scripts

Run from monorepo root using pnpm:

pnpm build - Build all packages (parallel, cached)
pnpm dev - Run all packages in dev mode
pnpm test - Run tests across all packages (parallel, cached)
pnpm lint - Lint all packages (parallel, cached)
pnpm typecheck - Type-check all packages (parallel, cached)
pnpm format - Format all files with Prettier
pnpm format:check - Check formatting without changes

Development Workflow

Before starting work:
- Ensure Node 22 is active: nvm use
- Install dependencies: pnpm install
During development:
- Run dev mode: pnpm dev (in specific package or root)
- Format code: pnpm format
Before committing:
- Type-check: pnpm typecheck
- Lint: pnpm lint
- Format check: pnpm format:check
- Run tests: pnpm test

Package Creation Conventions

When creating a new package in the monorepo:

Version Number: Always start new packages at version 1.0.0 (not 0.0.1)
- Example: "version": "1.0.0" in package.json
- This is a project preference for consistency
Package Structure:
- Follow existing package patterns (see cwc-types as reference)
- Include package.json, tsconfig.json extending base config
- Place source files in src/ directory
- Include appropriate build and typecheck scripts
Package Entry Points (CRITICAL - bundler resolution):
- Point main, types, and exports to ./src/index.ts (NOT ./dist)
- With bundler module resolution, we reference TypeScript source directly
- Example:
```
"main": "./src/index.ts",
"types": "./src/index.ts",
"exports": {
  ".": {
    "types": "./src/index.ts",
    "default": "./src/index.ts"
  }
}
```
- ❌ NEVER use ./dist/index.js or ./dist/index.d.ts
Package Naming:
- Use cwc- prefix for all CWC packages
- Use kebab-case: cwc-types, cwc-backend-utils, etc.
Package Documentation:
- Create packages/{package-name}/CLAUDE.md for package-specific patterns and conventions
- Document architecture decisions, design patterns, and critical implementation details
- Keep package docs focused on information needed for AI-assisted coding
Add Package Shortcut Script:
- Add a shortcut script to root package.json for the new package
- Format: "package-name-shortcut": "pnpm --filter cwc-package-name"
- Example: "backend-utils": "pnpm --filter cwc-backend-utils"
- This allows simplified commands: pnpm backend-utils add express instead of pnpm --filter cwc-backend-utils add express
- Keep shortcuts in alphabetical order in the scripts section

Key Architectural Decisions & Patterns

MariaDB Database

Strong Schema Enforcement
Transaction support
Efficient Joins
Data normalization
Sophisticated Querying and Analytics

Details: See packages/cwc-database/CLAUDE.md for complete database schema conventions.

TypeScript

Strict mode enabled (strict: true)
Shared types in cwc-types package; duplicating types in separate projects leads to inconsistencies, incompatibility, confusion, and extra work
Never use any - prefer unknown if type is truly unknown
Use string literal union types, not enums
Use type for entity definitions, not interface
Use undefined, never null - simplifies code by avoiding explicit checks for both values; aligns with TypeScript's optional property syntax (field?: string)
Run typecheck before committing

Details: See packages/cwc-types/CLAUDE.md for complete TypeScript patterns and type generation.

Path Construction (Searchability)

Use concatenated path strings in path.join() for better searchability:

// ✅ GOOD - searchable for "deployment/servers.json"
path.join(secretsPath, 'deployment/servers.json')

// ❌ AVOID - searching for "deployment/servers.json" won't find this
path.join(secretsPath, 'deployment', 'servers.json')

Exception: Directory navigation with .. should remain segmented:

// This is fine - navigating up directories
path.join(__dirname, '..', '..', 'templates')

Naming Conventions for Configuration Values

Clarity is critical for maintainability. Configuration names should clearly indicate:

What the value is for (its purpose)
Where it's used (which service/context)

Examples:

sqlClientApiKey - Clear: API key for SQL Client authentication
authenticationPublicKey - Unclear: Could apply to any auth system

Rule: When naming configuration values, prefer verbose, descriptive names over short, ambiguous ones. When a developer returns to the code after weeks or months, the name should immediately convey the purpose without requiring investigation.

Package-specific prefixes: When a configuration value is only used by one package, prefix it with the package context to avoid ambiguity:

storageLogPath / STORAGE_LOG_PATH - Clear: log path for cwc-storage
logPath / LOG_PATH - Unclear: which service uses this?

Secret and API Key Generation

Use crypto.randomBytes() for generating secrets and API keys:

import crypto from 'crypto';

// Generate a 256-bit (32-byte) cryptographically secure random key
const apiKey = crypto.randomBytes(32).toString('hex'); // 64-character hex string

This produces cryptographically secure random values suitable for:

API keys (e.g., STORAGE_API_KEY)
JWT secrets (e.g., USER_JWT_SECRET)
Any symmetric secret requiring high entropy

Cloud-Agnostic Microservices

CWC uses a microservices architecture deployed as Docker containers potentially deployed across multiple datacenters.

Vendor lock-in is a real business risk. Cloud providers can change pricing, deny service access, or deprecate features at any time.
Cloud-agnostic microservices architecture allows switching hosting providers with minimal effort.
Preparation for Scale - can scale by adding infrastructure (more containers, load balancers) rather than rewriting code and specific services can be scaled based on actual load patterns

Environment Configuration

NODE_ENV vs RUNTIME_ENVIRONMENT:

Variable	Purpose	Set By	Values
`NODE_ENV`	Build-time behavior	npm/bundlers	`development`, `production`, `test`
`RUNTIME_ENVIRONMENT`	Application runtime behavior	CWC deployment	`dev`, `test`, `prod`, `unit`, `e2e`

NODE_ENV (npm/Node.js ecosystem):

Controls build optimizations (minification, tree-shaking)
Affects dependency installation behavior
CWC does NOT read this in application config

RUNTIME_ENVIRONMENT (CWC application):

Controls application behavior (email sending, error verbosity, feature flags)
Type: RuntimeEnvironment from cwc-types
CWC config system reads this via loadConfig()

Rules:

Test scripts: RUNTIME_ENVIRONMENT=unit jest (not NODE_ENV=unit)
Backend config: Always read RUNTIME_ENVIRONMENT, never NODE_ENV
Each package reads configuration from .env file tailored to the runtime environment

1-to-1 Naming Convention:

Use consistent naming across all runtime environment references for searchability and clarity:

Runtime Environment	Env File	Config Flag	Mock Function
`dev`	`dev.cwc-*.env`	`isDev`	`createMockDevConfig()`
`prod`	`prod.cwc-*.env`	`isProd`	`createMockProdConfig()`
`unit`	`unit.cwc-*.env`	`isUnit`	`createMockUnitConfig()`
`e2e`	`e2e.cwc-*.env`	`isE2E`	`createMockE2EConfig()`
`test`	`test.cwc-*.env`	`isTest`	`createMockTestConfig()`

This consistency enables searching for Dev or Prod to find all related code paths.

Development Process

Tool, Framework, Version selection

mainstream, widely accepted, and thoroughly tested & proven tools only
the desire is to use the latest stable versions of the various tools

Adopt a "roll-your-own" mentality

we want to minimize the number of unnecessary dependencies to avoid headaches when upgrading our core tech stack
when it makes sense, we will build our own components and utilities rather than relying on a 3rd party package

Code Review Workflow Patterns

CRITICAL: When the developer provides comprehensive code review feedback and requests step-by-step discussion.

Developer Should Continue Providing Comprehensive Feedback Lists

Encourage the developer to provide ALL feedback items in a single comprehensive list. This is highly valuable because:

Gives full context about scope of changes
Allows identification of dependencies between issues
Helps spot patterns across multiple points
More efficient than addressing issues one at a time

Never discourage comprehensive feedback. The issue is not the list size, but how Claude Code presents the response.

Recognize Step-by-Step Request Signals

When the developer says any of these phrases:

"review each of these in order step by step"
"discuss each point one by one"
"let's go through these one at a time"
"walk me through each item"

This is a request for ITERATIVE discussion, not a comprehensive dump of all analysis.

Step-by-Step Review Pattern (Default for Code Reviews)

When developer provides comprehensive feedback with step-by-step request:

✅ Correct approach:

Present ONLY Point 1 with:
- The developer's original feedback for that point
- Claude's analysis and thoughts
- Any clarifying questions needed
- Recommendation for what to do
Wait for developer response and engage in discussion if needed
After Point 1 is resolved, present Point 2 using same format
Continue iteratively through all points
After all points discussed, ask "Ready to implement?" and show summary of agreed changes

Message format for each point:

## Point N: [Topic Name]

**Your Feedback:**
[Quote the developer's original feedback for this point]

**My Analysis:**
[Thoughts on this specific point only]

**Questions:** [If clarification needed]
- Question 1?
- Question 2?

**Recommendation:**
[What Claude thinks should be done]

---
*Waiting for your thoughts on Point N before moving to Point N+1.*

❌ What NOT to do:

Present all 10-15 points with full analysis at once
Make the developer reference "Point 7" or scroll to find what they want to discuss
Skip the iterative conversation pattern when explicitly requested

Alternative: Full Analysis First Pattern

Only use this pattern when developer explicitly requests it:

Developer says:

"Give me your analysis on all points first"
"Show me all your recommendations, then we'll discuss"
"I want to see the big picture before deciding"

In this case:

Present comprehensive analysis of all points
Wait for developer to identify which points need discussion
Focus conversation only on points developer has questions about

Benefits of Step-by-Step Pattern

Easy to follow: Each message is focused on one decision
Encourages discussion: Natural to discuss one topic at a time
No reference confusion: No need to say "regarding Point 7..."
Clear progress: Both parties know exactly where we are in the review
Better decisions: Focused attention leads to better analysis

Implementation Phase

After all review points are discussed and decisions made:

Summarize all agreed changes in a checklist format
Ask for explicit approval to proceed: "Ready to implement these changes?"
Proceed with implementation in logical groups
Update documentation if patterns/learnings emerged during review

Session 010 Learning: This pattern was established after Claude Code incorrectly presented all 14 review points at once despite clear request for step-by-step discussion. This made it difficult for the developer to engage in focused discussion on individual points.

never log config.secrets, these values are always REDACTED

packages/cwc-api/CLAUDE.md

cwc-api Package

Main business logic API for CWC application. Acts as the central orchestrator that handles CRUD operations, enforces business rules, and coordinates data flow between frontend applications and the database layer.

Architecture

Database-Connected Microservice:

Uses SqlClient from cwc-backend-utils to communicate with cwc-sql
Uses database-backed Logger for error logging
Never connects directly to database - all data access flows through cwc-sql
Coordinates with cwc-auth for session renewal

Layered Architecture:

Request → RequestHandler → QueryHandler/MutationHandler → SqlFunctions → SqlClient → cwc-sql

RequestHandler: Auth → context creation → route access check → delegation → session renewal
QueryHandler: Operation access check → execute query → format response
MutationHandler: Operation access check → execute mutation → format response
SqlFunctions: Atomic database operations (one function per table operation)

Request Pipeline

Express routes receive incoming HTTP requests
RequestHandler extracts JWT from Authorization header
JWT validated → authenticated context; No JWT → guest context
Route-level access policy checked
QueryHandler or MutationHandler executes business logic
SqlFunctions handle database operations through SqlClient
RequestHandler renews session (if authenticated and not auth error)
Response returned (with new JWT if session renewed)

Context Layer - Centralized Authentication

Location: src/context/

Architecture Decision: cwc-api does NOT duplicate JWT verification logic. All token validation goes through cwc-auth's /auth/v1/verify-token endpoint via AuthClient.

Trade-off: Additional HTTP call per request, but auth logic stays centralized in cwc-auth (single source of truth).

Files:

context.types.ts - AuthenticatedContext, GuestContext, RequestContext types
createContext.ts - Creates context from Authorization header
index.ts - Exports

Context Types:

// Authenticated user (valid JWT)
type AuthenticatedContext = {
  isAuthenticated: true;
  role: 'project-owner' | 'logged-on-user';  // Determined per-operation
  userPkId: number;
  username: string;
  ownedProjects: string[];
  payload: UserJwtPayload;
};

// Unauthenticated request (no/invalid JWT)
type GuestContext = {
  isAuthenticated: false;
  role: 'guest-user';
};

type RequestContext = AuthenticatedContext | GuestContext;

Usage:

import { createContext } from './context';
import { AuthClient } from 'cwc-backend-utils';

const context = await createContext({
  authHeader: req.headers.authorization,
  authClient: authClient,
});

if (context.isAuthenticated) {
  // TypeScript narrows to AuthenticatedContext
  console.log(context.userPkId, context.ownedProjects);
} else {
  // TypeScript narrows to GuestContext
  console.log(context.role);  // 'guest-user'
}

Graceful Degradation:

Missing token → guest context
Invalid token → guest context
Expired token → guest context
Auth service error → guest context (logged)
No errors thrown; auth failures result in guest access

Handler Architecture

Location: src/handlers/

Files:

handler.types.ts - Type definitions for handlers, operations, and responses
RequestHandler.ts - Entry point: route access check, delegation, session renewal
QueryHandler.ts - Read operations with pagination support
MutationHandler.ts - Write operations
responseUtils.ts - Shared response creation utilities (error responses, status code mapping)
index.ts - Exports

Handler Flow:

RequestHandler.processRequest()
├── checkRouteAccess() → 401/403 if denied (NO renewal)
├── buildOperationContext() → projectId, resourceId from path
├── delegate to QueryHandler or MutationHandler
│   ├── checkOperationAccess() → (stub for Phase 4)
│   ├── execute operation()
│   └── format response (no JWT)
├── if authenticated AND not auth error (401/403):
│   └── renewSession() → merge JWT into response
└── return final response

Session Renewal Strategy:

Centralized in RequestHandler (not Query/MutationHandler)
Renews on ALL requests except auth errors (401, 403)
Even failed operations (404, 500) trigger renewal to keep session active
New JWT merged into response body (response.body.jwt) for success responses
Renewal failure doesn't fail the request (graceful degradation, logged)
Guest users never trigger renewal

Error Code Mapping:

Error Code	HTTP Status
`UNAUTHORIZED`	401
`FORBIDDEN`	403
`NOT_FOUND`	404
`ALREADY_EXISTS`	400
`VALIDATION_ERROR`	400
`INVALID_PARAMETER`	400
`DATABASE_ERROR`	500
`INTERNAL_ERROR`	500

Role-Based Access Control

Roles:

Role	Description
`project-owner`	User owns the project being accessed
`logged-on-user`	Authenticated user (may not own the project)
`guest-user`	Unauthenticated request (read-only access)

Access Policy Levels:

Route-level: Can this role call this endpoint at all?
Operation-level: Can this role execute this specific operation? (Phase 4)
Context-aware: Does the user have the right relationship to the data? (e.g., ownership)

Tables Handled

Content Tables (Full CRUD + Soft Delete):

project
codingSession
codingSessionContent
codingSessionAttachment
comment
reaction
contentReport
abuseReport

Read-Only Tables:

featureFlag (all fields)
user (limited fields: userPkId, enabled, username, loginType, loginDate, otpValidated)

SqlFunction Naming Convention

Each table has a subdirectory in src/sql/ with these functions:

Function	Purpose
`select{Table}.ts`	Retrieve single record by identifier
`list{Table}s.ts`	Retrieve multiple records with filtering
`insert{Table}.ts`	Create new record
`update{Table}.ts`	Modify existing record
`delete{Table}.ts`	Hard delete (GDPR compliance)
`softDelete{Table}.ts`	Soft delete (set enabled=false)

Key Principles:

Single responsibility: Each SqlFunction does one thing
No business logic: SqlFunctions handle data access only
Soft-delete awareness: List queries automatically filter enabled=true
Composability: Queries/Mutations compose multiple SqlFunctions

cwc-auth Integration

Division of Responsibilities:

Concern	Owner
"Is this token valid?"	cwc-auth
"Who is this user?"	cwc-auth (via token claims)
"Can this user access this endpoint?"	cwc-api
"Is this user the owner of this project?"	cwc-api

Session Renewal Flow:

When cwc-api creates/deletes a project:

cwc-api performs the database operation
cwc-api calls cwc-auth /auth/v1/renew-session
cwc-auth issues new JWT with updated ownedProjects
cwc-api returns new JWT to client

Response Pattern

Standard Response Envelope:

// Success
{
  success: true,
  data: { ... },
  // Optional: pagination metadata
}

// Error
{
  success: false,
  errorCode: 'ERROR_CODE',
  errorMessage: 'Human-readable message',
  // Dev-only: errorDetail
}

Pagination (Offset-based):

{
  success: true,
  data: [...],
  pagination: {
    page: 1,
    pageSize: 20,
    totalCount: 100,
    hasMore: true
  }
}

Configuration

Required Environment Variables:

RUNTIME_ENVIRONMENT=dev
SERVICE_PORT=5040
DATA_URI=http://localhost:5020/data/v1
AUTH_URI=http://localhost:5005/auth/v1
APP_URL=http://localhost:3000
CORS_ORIGIN=*
DEV_CORS_ORIGIN=http://localhost:3000
RATE_LIMITER_POINTS=15
RATE_LIMITER_DURATION=1
DEBUG_MODE=OFF
LOG_ERRORS_TO_DATABASE=ON
USER_JWT_SECRET=...
SQL_CLIENT_API_KEY=...

API Versioning

URL-based versioning:

/api/v1/* routes to CwcApiV1 handlers
Each version lives in src/apis/CwcApiV{N}/
Route definitions in routes.ts, organized alphabetically

Critical Rules

SqlClient Usage:

Never provide createdDate or modifiedDate - handled by cwc-sql automatically
Always use SqlFunctions, never construct queries directly in business logic

Guest User Handling:

No JWT required - RequestHandler creates context with role: 'guest-user'
Guest users have read-only access to public content

Soft Delete:

All content tables support soft delete (enabled=false)
Hard delete available for GDPR compliance
List queries automatically filter enabled=true

Implementation Status

Active Development: This package is being implemented following cwc-api-implementation-checklist.md.

The checklist tracks 7 phases:

Package Foundation (config, Express service, health check) - Complete
Authentication & Context Layer (JWT, request context) - Complete
Handler Architecture (RequestHandler, QueryHandler, MutationHandler) - Complete
Access Policy System (route and operation policies)
SqlFunction Layer (CRUD operations for all tables)
CwcApiV1 Routes & Business Logic
Integration Testing & Final Review

Each phase includes: Implementation → Unit Tests → Security Review → Documentation Updates

Unit Testing

Test Infrastructure:

Jest 30.x with ts-jest for TypeScript ESM support
Test files: src/__tests__/**/*.test.ts
Setup: src/__tests__/setup.ts loads unit test environment via loadDotEnv
Run tests: pnpm api test or NODE_ENV=unit pnpm --filter cwc-api test

Mock Infrastructure (src/__tests__/mocks/):

Mock	Purpose
SqlClient Mocks
`createMockSqlClient()`	Full SqlClient mock with jest.fn() for all methods
`mockSelectSuccess/NotFound`	Configure SqlClient for select queries
`mockListSuccess`	Configure SqlClient for list queries
`mockInsertSuccess/Failure`	Configure SqlClient for inserts
`mockUpdateSuccess/NotFound`	Configure SqlClient for updates
`mockDeleteSuccess/NotFound`	Configure SqlClient for deletes
AuthClient Mocks
`createMockAuthClient()`	Full AuthClient mock (verifyToken, renewSession)
`createMockUserJwtPayload(overrides)`	Create UserJwtPayload with custom overrides
`mockVerifyTokenSuccess(client, payload?)`	Configure AuthClient to return success
`mockVerifyTokenFailure(client, error?)`	Configure AuthClient to return failure
`mockRenewSessionSuccess(client, jwt?)`	Configure renewSession to return new JWT
`mockRenewSessionFailure(client, error?)`	Configure renewSession to return failure
Route/Handler Mocks
`createMockRouteConfig(overrides)`	Create route config for testing
`createMockOperationContext(overrides)`	Create operation context for testing
`createMockGuestContext()`	Create guest (unauthenticated) context
`createMockAuthenticatedContext(overrides)`	Create authenticated user context
`mockOperationSuccess(routeConfig, data)`	Configure operation to succeed
`mockOperationFailure(routeConfig, code, msg)`	Configure operation to fail
`mockOperationThrows(routeConfig, error)`	Configure operation to throw
Config Mocks
`getUnitConfig()`	Load real config from unit.cwc-api.env
`createMockConfig(overrides)`	Create config with custom overrides
`createMockDevConfig(overrides)`	Mock config with isDev: true
`createMockProdConfig(overrides)`	Mock config with isProd: true
`createMockUnitConfig(overrides)`	Mock config with isUnit: true
Logger Mock
`createMockLogger()`	ILogger mock with logDebug, logError, logInformation

Testing Patterns:

RequestHandler tests (includes session renewal):

import {
  createMockAuthClient,
  createMockRouteConfig,
  createMockAuthenticatedContext,
  mockOperationSuccess,
  mockRenewSessionSuccess,
  getUnitConfig,
} from '../mocks';

describe('RequestHandler', () => {
  const unitConfig = getUnitConfig();
  const mockAuthClient = createMockAuthClient();

  it('should renew session on success', async () => {
    const routeConfig = createMockRouteConfig({ handlerType: 'query' });
    const context = createMockAuthenticatedContext();
    mockOperationSuccess(routeConfig, { id: 1 });
    mockRenewSessionSuccess(mockAuthClient, 'new-jwt');
    // RequestHandler uses 4 args: options, config, authClient, logger
    const handler = new RequestHandler(options, unitConfig, mockAuthClient, mockLogger);
    // ...
  });
});

QueryHandler/MutationHandler tests (no authClient, no renewal):

import {
  createMockRouteConfig,
  createMockAuthenticatedContext,
  mockOperationSuccess,
  getUnitConfig,
} from '../mocks';

describe('QueryHandler', () => {
  const unitConfig = getUnitConfig();

  it('should execute operation', async () => {
    const routeConfig = createMockRouteConfig();
    const context = createMockAuthenticatedContext();
    mockOperationSuccess(routeConfig, { id: 1 });
    // QueryHandler uses 3 args: options, config, logger
    const handler = new QueryHandler(options, unitConfig, undefined);
    // ...
  });
});

Related Packages

Depends On:

cwc-backend-utils (workspace) - SqlClient, Logger, Express service factory
cwc-schema (workspace) - Data validation
cwc-types (workspace) - Entity types, RuntimeEnvironment

Coordinates With:

cwc-auth - JWT validation, session renewal
cwc-sql - Database operations

Consumed By:

cwc-website - Frontend web application

packages/cwc-api/src/__tests__/config.test.ts

'use strict';

import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';

/**
 * Note: These tests cannot dynamically import loadConfig because the import chain
 * goes through cwc-backend-utils which imports uuid (an ESM module).
 *
 * Instead, we test the key parsing/validation functions directly.
 * Integration of loadConfig is tested via other tests that use the config mock.
 */

describe('Configuration Loading', () => {
  let originalEnv: NodeJS.ProcessEnv;
  let exitSpy: jest.SpiedFunction<typeof process.exit>;

  beforeEach(() => {
    // Save original environment
    originalEnv = { ...process.env };

    // Mock process.exit to prevent test termination
    exitSpy = jest.spyOn(process, 'exit').mockImplementation((code?: string | number | null) => {
      throw new Error(`process.exit called with ${code}`);
    }) as jest.SpiedFunction<typeof process.exit>;

    // Clear relevant environment variables
    delete process.env['RUNTIME_ENVIRONMENT'];
    delete process.env['SERVICE_PORT'];
    delete process.env['DATA_URI'];
    delete process.env['AUTH_URI'];
    delete process.env['APP_URL'];
    delete process.env['CORS_ORIGIN'];
    delete process.env['USER_JWT_SECRET'];
    delete process.env['SQL_CLIENT_API_KEY'];
    delete process.env['DEBUG_MODE'];
    delete process.env['LOG_ERRORS_TO_DATABASE'];
    delete process.env['RATE_LIMITER_POINTS'];
    delete process.env['RATE_LIMITER_DURATION'];
    delete process.env['DEV_CORS_ORIGIN'];
    delete process.env['END_TO_END_TESTING_MOCK_VALUES'];

    // Clear module cache
    jest.resetModules();
  });

  afterEach(() => {
    process.env = originalEnv;
    exitSpy.mockRestore();
  });

  describe('RuntimeEnvironment validation', () => {
    it('should accept valid runtime environments', () => {
      const validEnvs = ['dev', 'test', 'prod', 'unit', 'e2e'];

      for (const env of validEnvs) {
        expect(validEnvs.includes(env)).toBe(true);
      }
    });

    it('should reject invalid runtime environments', () => {
      const invalidEnvs = ['development', 'production', 'invalid', ''];
      const validEnvs = ['dev', 'test', 'prod', 'unit', 'e2e'];

      for (const env of invalidEnvs) {
        expect(validEnvs.includes(env)).toBe(false);
      }
    });
  });

  describe('Secret validation', () => {
    it('should require non-empty userJwtSecret', () => {
      const validSecret = 'my-secret-key-for-jwt-signing';
      const invalidSecrets = ['', undefined, null];

      expect(validSecret.length).toBeGreaterThan(0);
      for (const secret of invalidSecrets) {
        expect(!secret || (typeof secret === 'string' && secret.length === 0)).toBe(true);
      }
    });

    it('should require non-empty sqlClientApiKey', () => {
      const validApiKey = 'sql-client-api-key-for-authentication';
      const invalidKeys = ['', undefined, null];

      expect(validApiKey.length).toBeGreaterThan(0);
      for (const key of invalidKeys) {
        expect(!key || (typeof key === 'string' && key.length === 0)).toBe(true);
      }
    });
  });

  describe('Environment boolean derivations', () => {
    it('should correctly derive isProd', () => {
      const tests = [
        { env: 'prod', expected: true },
        { env: 'dev', expected: false },
        { env: 'test', expected: false },
        { env: 'unit', expected: false },
        { env: 'e2e', expected: false },
      ];

      for (const test of tests) {
        const isProd = test.env === 'prod';
        expect(isProd).toBe(test.expected);
      }
    });

    it('should correctly derive isDev', () => {
      const tests = [
        { env: 'dev', expected: true },
        { env: 'prod', expected: false },
        { env: 'test', expected: false },
        { env: 'unit', expected: false },
        { env: 'e2e', expected: false },
      ];

      for (const test of tests) {
        const isDev = test.env === 'dev';
        expect(isDev).toBe(test.expected);
      }
    });

    it('should correctly derive isTest', () => {
      const tests = [
        { env: 'test', expected: true },
        { env: 'dev', expected: false },
        { env: 'prod', expected: false },
        { env: 'unit', expected: false },
        { env: 'e2e', expected: false },
      ];

      for (const test of tests) {
        const isTest = test.env === 'test';
        expect(isTest).toBe(test.expected);
      }
    });

    it('should correctly derive isUnit', () => {
      const tests = [
        { env: 'unit', expected: true },
        { env: 'dev', expected: false },
        { env: 'prod', expected: false },
        { env: 'test', expected: false },
        { env: 'e2e', expected: false },
      ];

      for (const test of tests) {
        const isUnit = test.env === 'unit';
        expect(isUnit).toBe(test.expected);
      }
    });

    it('should correctly derive isE2E', () => {
      const tests = [
        { env: 'e2e', expected: true },
        { env: 'dev', expected: false },
        { env: 'prod', expected: false },
        { env: 'test', expected: false },
        { env: 'unit', expected: false },
      ];

      for (const test of tests) {
        const isE2E = test.env === 'e2e';
        expect(isE2E).toBe(test.expected);
      }
    });
  });

  describe('Port validation', () => {
    it('should accept valid port numbers', () => {
      const validPorts = [1, 80, 443, 3000, 5040, 65535];

      for (const port of validPorts) {
        const isValid = port >= 1 && port <= 65535;
        expect(isValid).toBe(true);
      }
    });

    it('should reject invalid port numbers', () => {
      const invalidPorts = [0, -1, 65536, 99999];

      for (const port of invalidPorts) {
        const isValid = port >= 1 && port <= 65535;
        expect(isValid).toBe(false);
      }
    });
  });

  describe('URL validation', () => {
    it('should accept valid HTTP URLs for dataUri', () => {
      const validUrls = [
        'http://localhost:5020/data/v1',
        'http://cwc-sql:5020/data/v1',
        'https://data.example.com/data/v1',
      ];

      for (const url of validUrls) {
        expect(url.startsWith('http')).toBe(true);
      }
    });

    it('should accept valid HTTP URLs for authUri', () => {
      const validUrls = [
        'http://localhost:5005/auth/v1',
        'http://cwc-auth:5005/auth/v1',
        'https://auth.example.com/auth/v1',
      ];

      for (const url of validUrls) {
        expect(url.startsWith('http')).toBe(true);
      }
    });

    it('should accept valid HTTP URLs for appUrl', () => {
      const validUrls = [
        'http://localhost:3000',
        'https://www.codingwithclaude.com',
      ];

      for (const url of validUrls) {
        expect(url.startsWith('http')).toBe(true);
      }
    });

    it('should reject invalid URLs', () => {
      const invalidUrls = ['not-a-url', 'ftp://files.com', '', 'localhost:3000'];

      for (const url of invalidUrls) {
        expect(url.startsWith('http')).toBe(false);
      }
    });
  });

  describe('Default values', () => {
    it('should have correct default rate limiter values', () => {
      const defaultRateLimiterPoints = 15;
      const defaultRateLimiterDuration = 1;

      expect(defaultRateLimiterPoints).toBe(15);
      expect(defaultRateLimiterDuration).toBe(1);
    });

    it('should have correct default devCorsOrigin', () => {
      const defaultDevCorsOrigin = 'http://localhost:3000';

      expect(defaultDevCorsOrigin).toBe('http://localhost:3000');
    });

    it('should have correct default debugMode and logErrorsToDatabase', () => {
      const defaultDebugMode = false;
      const defaultLogErrorsToDatabase = true;

      expect(defaultDebugMode).toBe(false);
      expect(defaultLogErrorsToDatabase).toBe(true);
    });
  });

  describe('Config type structure', () => {
    it('should have correct service name', () => {
      const serviceName = 'cwc-api';
      expect(serviceName).toBe('cwc-api');
    });

    it('should have secrets nested correctly', () => {
      const mockSecrets = {
        userJwtSecret: 'test-secret',
        sqlClientApiKey: 'test-api-key',
      };

      expect(mockSecrets.userJwtSecret).toBe('test-secret');
      expect(mockSecrets.sqlClientApiKey).toBe('test-api-key');
    });
  });
});

packages/cwc-api/src/__tests__/handlers/MutationHandler.test.ts

'use strict';

import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { MutationHandler } from '../../handlers/MutationHandler';
import {
  createMockRouteConfig,
  createMockAuthenticatedContext,
  mockOperationSuccess,
  mockOperationFailure,
  mockOperationThrows,
  getUnitConfig,
  createMockDevConfig,
  createMockProdConfig,
  createMockLogger,
} from '../mocks';
import type { MutationHandlerOptions } from '../../handlers/handler.types';

describe('MutationHandler', () => {
  const unitConfig = getUnitConfig();
  const mockProdConfig = createMockProdConfig();

  beforeEach(() => {
    jest.clearAllMocks();
  });

  describe('Successful Operations', () => {
    it('should return 200 with data on successful mutation', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationSuccess(routeConfig, { id: 1, created: true });

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: { name: 'New Item' },
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
      if (response.body.success) {
        expect(response.body.data).toEqual({ id: 1, created: true });
      }
    });

    it('should return 200 for all operations (RPC-style, no 201)', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationSuccess(routeConfig, { id: 999, status: 'created' });

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      // All POST operations return 200, not 201
      expect(response.statusCode).toBe(200);
    });

    it('should not include jwt in response (handled by RequestHandler)', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationSuccess(routeConfig, { id: 1 });

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
      if (response.body.success) {
        expect(response.body.jwt).toBeUndefined();
      }
    });
  });

  describe('Error Responses', () => {
    it('should return 404 for NOT_FOUND error code', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationFailure(routeConfig, 'NOT_FOUND', 'Resource not found');

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(404);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('NOT_FOUND');
        expect(response.body.errorMessage).toBe('Resource not found');
      }
    });

    it('should return 400 for ALREADY_EXISTS error code', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationFailure(routeConfig, 'ALREADY_EXISTS', 'Resource already exists');

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(400);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('ALREADY_EXISTS');
      }
    });

    it('should return 400 for VALIDATION_ERROR', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationFailure(routeConfig, 'VALIDATION_ERROR', 'Invalid input');

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(400);
      expect(response.body.success).toBe(false);
    });

    it('should return 500 for DATABASE_ERROR', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationFailure(routeConfig, 'DATABASE_ERROR', 'Database connection failed');

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(500);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('DATABASE_ERROR');
      }
    });
  });

  describe('Exception Handling', () => {
    it('should catch errors and return 500 response', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationThrows(routeConfig, new Error('Unexpected database error'));

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(500);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('INTERNAL_ERROR');
        expect(response.body.errorMessage).toBe('An internal error occurred');
      }
    });

    it('should include error detail when isDev is true', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      const mockDevConfig = createMockDevConfig();
      mockOperationThrows(routeConfig, new Error('Detailed error message'));

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, mockDevConfig, undefined);
      const response = await handler.processRequest();

      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorDetail).toBe('Detailed error message');
      }
    });

    it('should not include error detail in production mode', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationThrows(routeConfig, new Error('Detailed error message'));

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, mockProdConfig, undefined);
      const response = await handler.processRequest();

      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorDetail).toBeUndefined();
      }
    });

    it('should log errors when logger is provided', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      const mockLogger = createMockLogger();
      mockOperationThrows(routeConfig, new Error('Test error'));

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, mockLogger);
      await handler.processRequest();

      expect(mockLogger.logError).toHaveBeenCalled();
    });
  });

  describe('Operation Access (Phase 3 Stub)', () => {
    it('should allow operation access (stub always returns allowed)', async () => {
      const routeConfig = createMockRouteConfig({ handlerType: 'mutation' });
      const context = createMockAuthenticatedContext();
      mockOperationSuccess(routeConfig, { id: 1 });

      const options: MutationHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new MutationHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      // Operation access is stubbed to always allow in Phase 3
      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
    });
  });
});

packages/cwc-api/src/__tests__/handlers/QueryHandler.test.ts

2 versions

Version 1

'use strict';

import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { QueryHandler } from '../../handlers/QueryHandler';
import {
  createMockRouteConfig,
  createMockGuestContext,
  createMockAuthenticatedContext,
  mockOperationSuccess,
  mockOperationFailure,
  mockOperationThrows,
  getUnitConfig,
  createMockDevConfig,
  createMockProdConfig,
  createMockLogger,
} from '../mocks';
import type { QueryHandlerOptions } from '../../handlers/handler.types';

describe('QueryHandler', () => {
  const unitConfig = getUnitConfig();
  const mockProdConfig = createMockProdConfig();

  beforeEach(() => {
    jest.clearAllMocks();
  });

  describe('Successful Operations', () => {
    it('should return 200 with data on successful query', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationSuccess(routeConfig, { id: 1, name: 'test' });

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
      if (response.body.success) {
        expect(response.body.data).toEqual({ id: 1, name: 'test' });
      }
    });

    it('should include pagination when operation returns it', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      const pagination = { page: 1, pageSize: 20, totalCount: 100, hasMore: true };
      mockOperationSuccess(routeConfig, [{ id: 1 }, { id: 2 }], pagination);

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
      if (response.body.success) {
        expect(response.body.pagination).toEqual(pagination);
      }
    });

    it('should not include jwt in response (handled by RequestHandler)', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockAuthenticatedContext();
      mockOperationSuccess(routeConfig, { id: 1 });

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
      if (response.body.success) {
        expect(response.body.jwt).toBeUndefined();
      }
    });
  });

  describe('Error Responses', () => {
    it('should return 404 for NOT_FOUND error code', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationFailure(routeConfig, 'NOT_FOUND', 'Resource not found');

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(404);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('NOT_FOUND');
        expect(response.body.errorMessage).toBe('Resource not found');
      }
    });

    it('should return 400 for VALIDATION_ERROR', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationFailure(routeConfig, 'VALIDATION_ERROR', 'Invalid input');

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(400);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('VALIDATION_ERROR');
      }
    });

    it('should return 403 for OPERATION_ACCESS_DENIED', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationFailure(routeConfig, 'OPERATION_ACCESS_DENIED', 'Not permitted');

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(403);
      expect(response.body.success).toBe(false);
    });

    it('should return 500 for DATABASE_ERROR', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationFailure(routeConfig, 'DATABASE_ERROR', 'Database connection failed');

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(500);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('DATABASE_ERROR');
      }
    });
  });

  describe('Exception Handling', () => {
    it('should catch errors and return 500 response', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationThrows(routeConfig, new Error('Unexpected database error'));

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(500);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('INTERNAL_ERROR');
        expect(response.body.errorMessage).toBe('An internal error occurred');
      }
    });

    it('should include error detail when isDev is true', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      const mockDevConfig = createMockDevConfig();
      mockOperationThrows(routeConfig, new Error('Detailed error message'));

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, mockDevConfig, undefined);
      const response = await handler.processRequest();

      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorDetail).toBe('Detailed error message');
      }
    });

    it('should not include error detail in production mode', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationThrows(routeConfig, new Error('Detailed error message'));

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      // mockProdConfig has isDevelopment: false
      const handler = new QueryHandler(options, mockProdConfig, undefined);
      const response = await handler.processRequest();

      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorDetail).toBeUndefined();
      }
    });

    it('should log errors when logger is provided', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockAuthenticatedContext();
      const mockLogger = createMockLogger();
      mockOperationThrows(routeConfig, new Error('Test error'));

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, mockLogger);
      await handler.processRequest();

      expect(mockLogger.logError).toHaveBeenCalled();
    });
  });

  describe('Operation Access (Phase 3 Stub)', () => {
    it('should allow operation access (stub always returns allowed)', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationSuccess(routeConfig, { id: 1 });

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      // Operation access is stubbed to always allow in Phase 3
      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
    });
  });
});

Version 2 (latest)

'use strict';

import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { QueryHandler } from '../../handlers/QueryHandler';
import {
  createMockRouteConfig,
  createMockGuestContext,
  createMockAuthenticatedContext,
  mockOperationSuccess,
  mockOperationFailure,
  mockOperationThrows,
  getUnitConfig,
  createMockDevConfig,
  createMockProdConfig,
  createMockLogger,
} from '../mocks';
import type { QueryHandlerOptions } from '../../handlers/handler.types';

describe('QueryHandler', () => {
  const unitConfig = getUnitConfig();
  const mockProdConfig = createMockProdConfig();

  beforeEach(() => {
    jest.clearAllMocks();
  });

  describe('Successful Operations', () => {
    it('should return 200 with data on successful query', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationSuccess(routeConfig, { id: 1, name: 'test' });

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
      if (response.body.success) {
        expect(response.body.data).toEqual({ id: 1, name: 'test' });
      }
    });

    it('should include pagination when operation returns it', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      const pagination = { page: 1, pageSize: 20, totalCount: 100, hasMore: true };
      mockOperationSuccess(routeConfig, [{ id: 1 }, { id: 2 }], pagination);

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
      if (response.body.success) {
        expect(response.body.pagination).toEqual(pagination);
      }
    });

    it('should not include jwt in response (handled by RequestHandler)', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockAuthenticatedContext();
      mockOperationSuccess(routeConfig, { id: 1 });

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
      if (response.body.success) {
        expect(response.body.jwt).toBeUndefined();
      }
    });
  });

  describe('Error Responses', () => {
    it('should return 404 for NOT_FOUND error code', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationFailure(routeConfig, 'NOT_FOUND', 'Resource not found');

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(404);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('NOT_FOUND');
        expect(response.body.errorMessage).toBe('Resource not found');
      }
    });

    it('should return 400 for VALIDATION_ERROR', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationFailure(routeConfig, 'VALIDATION_ERROR', 'Invalid input');

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(400);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('VALIDATION_ERROR');
      }
    });

    it('should return 403 for OPERATION_ACCESS_DENIED', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationFailure(routeConfig, 'OPERATION_ACCESS_DENIED', 'Not permitted');

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(403);
      expect(response.body.success).toBe(false);
    });

    it('should return 500 for DATABASE_ERROR', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationFailure(routeConfig, 'DATABASE_ERROR', 'Database connection failed');

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(500);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('DATABASE_ERROR');
      }
    });
  });

  describe('Exception Handling', () => {
    it('should catch errors and return 500 response', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationThrows(routeConfig, new Error('Unexpected database error'));

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      expect(response.statusCode).toBe(500);
      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorCode).toBe('INTERNAL_ERROR');
        expect(response.body.errorMessage).toBe('An internal error occurred');
      }
    });

    it('should include error detail when isDev is true', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      const mockDevConfig = createMockDevConfig();
      mockOperationThrows(routeConfig, new Error('Detailed error message'));

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, mockDevConfig, undefined);
      const response = await handler.processRequest();

      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorDetail).toBe('Detailed error message');
      }
    });

    it('should not include error detail in production mode', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationThrows(routeConfig, new Error('Detailed error message'));

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      // mockProdConfig has isDev: false
      const handler = new QueryHandler(options, mockProdConfig, undefined);
      const response = await handler.processRequest();

      expect(response.body.success).toBe(false);
      if (!response.body.success) {
        expect(response.body.errorDetail).toBeUndefined();
      }
    });

    it('should log errors when logger is provided', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockAuthenticatedContext();
      const mockLogger = createMockLogger();
      mockOperationThrows(routeConfig, new Error('Test error'));

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: 'Bearer token',
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, mockLogger);
      await handler.processRequest();

      expect(mockLogger.logError).toHaveBeenCalled();
    });
  });

  describe('Operation Access (Phase 3 Stub)', () => {
    it('should allow operation access (stub always returns allowed)', async () => {
      const routeConfig = createMockRouteConfig();
      const context = createMockGuestContext();
      mockOperationSuccess(routeConfig, { id: 1 });

      const options: QueryHandlerOptions = {
        context,
        routeConfig,
        authHeader: undefined,
        payload: {},
        operationContext: { context },
      };

      const handler = new QueryHandler(options, unitConfig, undefined);
      const response = await handler.processRequest();

      // Operation access is stubbed to always allow in Phase 3
      expect(response.statusCode).toBe(200);
      expect(response.body.success).toBe(true);
    });
  });
});

packages/cwc-api/src/__tests__/mocks/config.mock.ts

2 versions

Version 1

'use strict';

import type { CwcApiConfig } from '../../config/config.types';
import { loadConfig } from '../../config';

/**
 * Gets the real config loaded from unit.cwc-api.env
 */
export function getUnitConfig(): CwcApiConfig {
  return loadConfig();
}

/**
 * Creates a mock config by applying overrides to the loaded unit config
 * Useful when you need to test specific config variations
 */
export function createMockConfig(overrides?: Partial<CwcApiConfig>): CwcApiConfig {
  const baseConfig = loadConfig();
  return { ...baseConfig, ...overrides };
}

/**
 * Creates a mock prod config for testing production error behavior
 */
export function createMockProdConfig(overrides?: Partial<CwcApiConfig>): CwcApiConfig {
  return createMockConfig({
    runtimeEnvironment: 'prod',
    isProd: true,
    isDev: false,
    isTest: false,
    isUnit: false,
    isE2E: false,
    debugMode: false,
    ...overrides,
  });
}

/**
 * Creates a mock unit config (should match what's loaded from unit.cwc-api.env)
 */
export function createMockUnitConfig(overrides?: Partial<CwcApiConfig>): CwcApiConfig {
  return createMockConfig({
    runtimeEnvironment: 'unit',
    isProduction: false,
    isDevelopment: false,
    isTest: false,
    isUnitTest: true,
    isEndToEnd: false,
    debugMode: false,
    ...overrides,
  });
}

/**
 * Creates a mock dev config for testing dev-mode behavior
 * Has isDevelopment: true so error details are exposed
 */
export function createMockDevConfig(overrides?: Partial<CwcApiConfig>): CwcApiConfig {
  return createMockConfig({
    runtimeEnvironment: 'dev',
    isProduction: false,
    isDevelopment: true,
    isTest: false,
    isUnitTest: false,
    isEndToEnd: false,
    debugMode: true,
    ...overrides,
  });
}

Version 2 (latest)

'use strict';

import type { CwcApiConfig } from '../../config/config.types';
import { loadConfig } from '../../config';

/**
 * Gets the real config loaded from unit.cwc-api.env
 */
export function getUnitConfig(): CwcApiConfig {
  return loadConfig();
}

/**
 * Creates a mock config by applying overrides to the loaded unit config
 * Useful when you need to test specific config variations
 */
export function createMockConfig(overrides?: Partial<CwcApiConfig>): CwcApiConfig {
  const baseConfig = loadConfig();
  return { ...baseConfig, ...overrides };
}

/**
 * Creates a mock prod config for testing production error behavior
 */
export function createMockProdConfig(overrides?: Partial<CwcApiConfig>): CwcApiConfig {
  return createMockConfig({
    runtimeEnvironment: 'prod',
    isProd: true,
    isDev: false,
    isTest: false,
    isUnit: false,
    isE2E: false,
    debugMode: false,
    ...overrides,
  });
}

/**
 * Creates a mock unit config (should match what's loaded from unit.cwc-api.env)
 */
export function createMockUnitConfig(overrides?: Partial<CwcApiConfig>): CwcApiConfig {
  return createMockConfig({
    runtimeEnvironment: 'unit',
    isProd: false,
    isDev: false,
    isTest: false,
    isUnit: true,
    isE2E: false,
    debugMode: false,
    ...overrides,
  });
}

/**
 * Creates a mock dev config for testing dev-mode behavior
 * Has isDev: true so error details are exposed
 */
export function createMockDevConfig(overrides?: Partial<CwcApiConfig>): CwcApiConfig {
  return createMockConfig({
    runtimeEnvironment: 'dev',
    isProd: false,
    isDev: true,
    isTest: false,
    isUnit: false,
    isE2E: false,
    debugMode: true,
    ...overrides,
  });
}

packages/cwc-api/src/config/config.types.ts

2 versions

Version 1

import type { RuntimeEnvironment } from 'cwc-types';

/**
 * Secret configuration values for cwc-api
 * These values must be provided via secrets file, never committed to code
 */
export type CwcApiConfigSecrets = {
  userJwtSecret: string;
  sqlClientApiKey: string;
};

/**
 * Configuration for the cwc-api microservice
 */
export type CwcApiConfig = {
  // Environment (derived - skipped in .env generation)
  runtimeEnvironment: RuntimeEnvironment;
  isProd: boolean;
  isDev: boolean;
  isTest: boolean;
  isUnit: boolean;
  isE2E: boolean;

  // Service
  name: string;
  servicePort: number;
  dataUri: string;
  authUri: string;
  appUrl: string;

  // Security
  corsOrigin: string;

  // Rate limiting
  rateLimiterPoints: number;
  rateLimiterDuration: number;

  // Development settings
  devCorsOrigin: string;

  // Debugging
  debugMode: boolean;
  logErrorsToDatabase: boolean;

  // E2E testing
  endToEndMockValues?: Record<string, string> | undefined;

  // Secrets (nested)
  secrets: CwcApiConfigSecrets;
};

Version 2 (latest)

import type { RuntimeEnvironment } from 'cwc-types';

/**
 * Secret configuration values for cwc-api
 * These values must be provided via secrets file, never committed to code
 */
export type CwcApiConfigSecrets = {
  userJwtSecret: string;
  sqlClientApiKey: string;
};

/**
 * Configuration for the cwc-api microservice
 */
export type CwcApiConfig = {
  // Environment (derived - skipped in .env generation)
  runtimeEnvironment: RuntimeEnvironment;
  isProd: boolean;
  isDev: boolean;
  isTest: boolean;
  isUnit: boolean;
  isE2E: boolean;

  // Service
  name: string;
  servicePort: number;
  dataUri: string;
  authUri: string;
  appUrl: string;

  // Security
  corsOrigin: string;

  // Rate limiting
  rateLimiterPoints: number;
  rateLimiterDuration: number;

  // Dev settings
  devCorsOrigin: string;

  // Debugging
  debugMode: boolean;
  logErrorsToDatabase: boolean;

  // E2E testing
  endToEndMockValues?: Record<string, string> | undefined;

  // Secrets (nested)
  secrets: CwcApiConfigSecrets;
};

packages/cwc-api/src/config/loadConfig.ts

2 versions

Version 1

import type { RuntimeEnvironment } from 'cwc-types';
import { requireEnv, optionalEnv, parseNumber, parseBoolean, parseJson } from 'cwc-backend-utils';
import type { CwcApiConfig } from './config.types';

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcApiConfig | undefined;

export function loadConfig(): CwcApiConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProd = runtimeEnvironment === 'prod';
    const isDev = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnit = runtimeEnvironment === 'unit';
    const isE2E = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcApiConfig = {
      // Environment
      runtimeEnvironment,
      isProd,
      isDev,
      isTest,
      isUnit,
      isE2E,

      // Service
      name: 'cwc-api',
      servicePort: parseNumber('SERVICE_PORT'),
      dataUri: requireEnv('DATA_URI'),
      authUri: requireEnv('AUTH_URI'),
      appUrl: requireEnv('APP_URL'),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),

      // Rate limiting
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 15),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 1),

      // Development settings
      devCorsOrigin: optionalEnv('DEV_CORS_ORIGIN', 'http://localhost:3000'),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE', false),
      logErrorsToDatabase: parseBoolean('LOG_ERRORS_TO_DATABASE', true),

      // E2E testing
      endToEndMockValues: isEndToEnd
        ? parseJson<Record<string, string>>('END_TO_END_TESTING_MOCK_VALUES', undefined)
        : undefined,

      // Secrets (nested)
      secrets: {
        userJwtSecret: requireEnv('USER_JWT_SECRET'),
        sqlClientApiKey: requireEnv('SQL_CLIENT_API_KEY'),
      },
    };

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Validate required URLs
    if (!config.dataUri.startsWith('http')) {
      throw new Error('DATA_URI must be a valid HTTP URL');
    }
    if (!config.authUri.startsWith('http')) {
      throw new Error('AUTH_URI must be a valid HTTP URL');
    }
    if (!config.appUrl.startsWith('http')) {
      throw new Error('APP_URL must be a valid HTTP URL');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-api] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  Data URI: ${config.dataUri}`);
      console.log(`  Auth URI: ${config.authUri}`);
      console.log(`  App URL: ${config.appUrl}`);
      console.log(`  CORS Origin: ${config.corsOrigin}`);
      console.log(
        `  Rate Limiter: ${config.rateLimiterPoints} points / ${config.rateLimiterDuration}s`
      );
      console.log(`  User JWT Secret: [REDACTED]`);
      console.log(`  SQL Client API Key: [REDACTED]`);
      console.log(`  Debug Mode: ${config.debugMode}`);
      console.log(`  Log Errors to Database: ${config.logErrorsToDatabase}`);
    }

    return config;
  } catch (error) {
    console.error('[cwc-api] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

Version 2 (latest)

import type { RuntimeEnvironment } from 'cwc-types';
import { requireEnv, optionalEnv, parseNumber, parseBoolean, parseJson } from 'cwc-backend-utils';
import type { CwcApiConfig } from './config.types';

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcApiConfig | undefined;

export function loadConfig(): CwcApiConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProd = runtimeEnvironment === 'prod';
    const isDev = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnit = runtimeEnvironment === 'unit';
    const isE2E = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcApiConfig = {
      // Environment
      runtimeEnvironment,
      isProd,
      isDev,
      isTest,
      isUnit,
      isE2E,

      // Service
      name: 'cwc-api',
      servicePort: parseNumber('SERVICE_PORT'),
      dataUri: requireEnv('DATA_URI'),
      authUri: requireEnv('AUTH_URI'),
      appUrl: requireEnv('APP_URL'),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),

      // Rate limiting
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 15),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 1),

      // Dev settings
      devCorsOrigin: optionalEnv('DEV_CORS_ORIGIN', 'http://localhost:3000'),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE', false),
      logErrorsToDatabase: parseBoolean('LOG_ERRORS_TO_DATABASE', true),

      // E2E testing
      endToEndMockValues: isE2E
        ? parseJson<Record<string, string>>('END_TO_END_TESTING_MOCK_VALUES', undefined)
        : undefined,

      // Secrets (nested)
      secrets: {
        userJwtSecret: requireEnv('USER_JWT_SECRET'),
        sqlClientApiKey: requireEnv('SQL_CLIENT_API_KEY'),
      },
    };

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Validate required URLs
    if (!config.dataUri.startsWith('http')) {
      throw new Error('DATA_URI must be a valid HTTP URL');
    }
    if (!config.authUri.startsWith('http')) {
      throw new Error('AUTH_URI must be a valid HTTP URL');
    }
    if (!config.appUrl.startsWith('http')) {
      throw new Error('APP_URL must be a valid HTTP URL');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-api] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  Data URI: ${config.dataUri}`);
      console.log(`  Auth URI: ${config.authUri}`);
      console.log(`  App URL: ${config.appUrl}`);
      console.log(`  CORS Origin: ${config.corsOrigin}`);
      console.log(
        `  Rate Limiter: ${config.rateLimiterPoints} points / ${config.rateLimiterDuration}s`
      );
      console.log(`  User JWT Secret: [REDACTED]`);
      console.log(`  SQL Client API Key: [REDACTED]`);
      console.log(`  Debug Mode: ${config.debugMode}`);
      console.log(`  Log Errors to Database: ${config.logErrorsToDatabase}`);
    }

    return config;
  } catch (error) {
    console.error('[cwc-api] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

packages/cwc-api/src/handlers/RequestHandler.ts

'use strict';

import type { ILogger, AuthClient } from 'cwc-backend-utils';
import type { CwcApiConfig } from '../config';
import type {
  CwcApiHandler,
  CwcApiHandlerResponse,
  CwcApiSuccessResponse,
  RequestHandlerOptions,
  RouteAccessResult,
  OperationContext,
} from './handler.types';
import { QueryHandler } from './QueryHandler';
import { MutationHandler } from './MutationHandler';
import { createInternalErrorResponse } from './responseUtils';

const codeLocation = 'handlers/RequestHandler.ts';

/**
 * RequestHandler - Entry point for processing API requests
 *
 * Responsibilities:
 * 1. Check route-level access based on context role
 * 2. Build operation context with path params
 * 3. Delegate to QueryHandler or MutationHandler based on handlerType
 * 4. Renew session for authenticated users (except on auth errors)
 */
export class RequestHandler implements CwcApiHandler {
  private options: RequestHandlerOptions;
  private config: CwcApiConfig;
  private authClient: AuthClient;
  private logger: ILogger | undefined;

  constructor(
    options: RequestHandlerOptions,
    config: CwcApiConfig,
    authClient: AuthClient,
    logger: ILogger | undefined
  ) {
    this.options = options;
    this.config = config;
    this.authClient = authClient;
    this.logger = logger;
  }

  public async processRequest(): Promise<CwcApiHandlerResponse> {
    const { context, routeConfig, payload, authHeader, pathParams } = this.options;

    try {
      // Step 1: Check route-level access
      const routeAccess = this.checkRouteAccess();
      if (!routeAccess.allowed) {
        // No session renewal for auth errors
        return this.createAccessDeniedResponse(routeAccess.reason);
      }

      // Step 2: Build operation context
      const operationContext: OperationContext = {
        context,
        projectId: pathParams?.['projectId'],
        resourceId: pathParams?.['resourceId'],
      };

      // Step 3: Delegate to appropriate handler
      let response: CwcApiHandlerResponse;
      if (routeConfig.handlerType === 'query') {
        const queryHandler = new QueryHandler(
          {
            context,
            routeConfig,
            authHeader,
            payload,
            operationContext,
          },
          this.config,
          this.logger
        );
        response = await queryHandler.processRequest();
      } else {
        const mutationHandler = new MutationHandler(
          {
            context,
            routeConfig,
            authHeader,
            payload,
            operationContext,
          },
          this.config,
          this.logger
        );
        response = await mutationHandler.processRequest();
      }

      // Step 4: Renew session for authenticated users (except on auth errors)
      const isAuthError = response.statusCode === 401 || response.statusCode === 403;
      if (context.isAuthenticated && !isAuthError) {
        const renewResult = await this.authClient.renewSession(authHeader);
        if (renewResult.success && response.body.success) {
          // Add JWT to successful response
          (response.body as CwcApiSuccessResponse).jwt = renewResult.jwt;
        } else if (!renewResult.success) {
          // Log warning but don't fail the operation
          this.logger?.logError({
            userPkId: context.userPkId,
            codeLocation,
            message: `Session renewal failed for ${routeConfig.path}`,
            error: renewResult.error,
          });
        }
      }

      return response;
    } catch (error) {
      this.logger?.logError({
        userPkId: context.isAuthenticated ? context.userPkId : undefined,
        codeLocation,
        message: `Error processing request ${routeConfig.path}`,
        error,
      });

      return createInternalErrorResponse(this.config, error);
    }
  }

  /**
   * Check if the current context role can access this route
   * Compares context.role against routeConfig.allowedRoles
   */
  private checkRouteAccess(): RouteAccessResult {
    const { context, routeConfig } = this.options;
    const { allowedRoles } = routeConfig;

    // Check if the current role is in allowedRoles
    if (allowedRoles.includes(context.role)) {
      return { allowed: true };
    }

    // For authenticated users with 'project-owner' role requirement,
    // 'logged-on-user' should also be allowed (ownership check happens at operation level)
    if (
      context.isAuthenticated &&
      context.role === 'logged-on-user' &&
      allowedRoles.includes('project-owner')
    ) {
      return { allowed: true };
    }

    return {
      allowed: false,
      reason: `Role '${context.role}' cannot access route ${routeConfig.path}`,
    };
  }

  private createAccessDeniedResponse(reason?: string): CwcApiHandlerResponse {
    const { context } = this.options;

    // Use 401 for unauthenticated, 403 for authenticated but not allowed
    const statusCode = context.isAuthenticated ? 403 : 401;
    const errorCode = context.isAuthenticated ? 'FORBIDDEN' : 'UNAUTHORIZED';

    return {
      statusCode,
      body: {
        success: false,
        errorCode,
        errorMessage: 'Access denied',
        ...(this.config.isDev && reason ? { errorDetail: reason } : {}),
      },
    };
  }
}

packages/cwc-api/src/handlers/responseUtils.ts

2 versions

Version 1

'use strict';

import type { CwcApiConfig } from '../config';
import type { CwcApiHandlerResponse, CwcApiErrorCode } from './handler.types';

/**
 * Maps error codes to appropriate HTTP status codes
 */
export function mapErrorCodeToStatus(errorCode: CwcApiErrorCode): 400 | 401 | 403 | 404 | 500 {
  switch (errorCode) {
    case 'NOT_FOUND':
      return 404;
    case 'VALIDATION_ERROR':
    case 'INVALID_PARAMETER':
    case 'ALREADY_EXISTS':
      return 400;
    case 'UNAUTHORIZED':
      return 401;
    case 'FORBIDDEN':
    case 'ROUTE_ACCESS_DENIED':
    case 'OPERATION_ACCESS_DENIED':
      return 403;
    case 'INTERNAL_ERROR':
    case 'DATABASE_ERROR':
    case 'AUTH_SERVICE_ERROR':
      return 500;
    default:
      return 500;
  }
}

/**
 * Creates a 403 response for operation access denied
 */
export function createOperationDeniedResponse(
  config: CwcApiConfig,
  reason?: string
): CwcApiHandlerResponse {
  return {
    statusCode: 403,
    body: {
      success: false,
      errorCode: 'OPERATION_ACCESS_DENIED',
      errorMessage: 'Operation not permitted',
      ...(config.isDev && reason ? { errorDetail: reason } : {}),
    },
  };
}

/**
 * Creates an error response with appropriate status code based on error code
 */
export function createOperationErrorResponse(
  errorCode: CwcApiErrorCode,
  errorMessage: string
): CwcApiHandlerResponse {
  const statusCode = mapErrorCodeToStatus(errorCode);

  return {
    statusCode,
    body: {
      success: false,
      errorCode,
      errorMessage,
    },
  };
}

/**
 * Creates a 500 internal error response
 */
export function createInternalErrorResponse(
  config: CwcApiConfig,
  error: unknown
): CwcApiHandlerResponse {
  return {
    statusCode: 500,
    body: {
      success: false,
      errorCode: 'INTERNAL_ERROR',
      errorMessage: 'An internal error occurred',
      ...(config.isDevelopment && error instanceof Error
        ? { errorDetail: error.message }
        : {}),
    },
  };
}

Version 2 (latest)

'use strict';

import type { CwcApiConfig } from '../config';
import type { CwcApiHandlerResponse, CwcApiErrorCode } from './handler.types';

/**
 * Maps error codes to appropriate HTTP status codes
 */
export function mapErrorCodeToStatus(errorCode: CwcApiErrorCode): 400 | 401 | 403 | 404 | 500 {
  switch (errorCode) {
    case 'NOT_FOUND':
      return 404;
    case 'VALIDATION_ERROR':
    case 'INVALID_PARAMETER':
    case 'ALREADY_EXISTS':
      return 400;
    case 'UNAUTHORIZED':
      return 401;
    case 'FORBIDDEN':
    case 'ROUTE_ACCESS_DENIED':
    case 'OPERATION_ACCESS_DENIED':
      return 403;
    case 'INTERNAL_ERROR':
    case 'DATABASE_ERROR':
    case 'AUTH_SERVICE_ERROR':
      return 500;
    default:
      return 500;
  }
}

/**
 * Creates a 403 response for operation access denied
 */
export function createOperationDeniedResponse(
  config: CwcApiConfig,
  reason?: string
): CwcApiHandlerResponse {
  return {
    statusCode: 403,
    body: {
      success: false,
      errorCode: 'OPERATION_ACCESS_DENIED',
      errorMessage: 'Operation not permitted',
      ...(config.isDev && reason ? { errorDetail: reason } : {}),
    },
  };
}

/**
 * Creates an error response with appropriate status code based on error code
 */
export function createOperationErrorResponse(
  errorCode: CwcApiErrorCode,
  errorMessage: string
): CwcApiHandlerResponse {
  const statusCode = mapErrorCodeToStatus(errorCode);

  return {
    statusCode,
    body: {
      success: false,
      errorCode,
      errorMessage,
    },
  };
}

/**
 * Creates a 500 internal error response
 */
export function createInternalErrorResponse(
  config: CwcApiConfig,
  error: unknown
): CwcApiHandlerResponse {
  return {
    statusCode: 500,
    body: {
      success: false,
      errorCode: 'INTERNAL_ERROR',
      errorMessage: 'An internal error occurred',
      ...(config.isDev && error instanceof Error
        ? { errorDetail: error.message }
        : {}),
    },
  };
}

packages/cwc-api/src/index.ts

2 versions

Version 1

import {
  loadDotEnv,
  createExpressService,
  // SqlClient, // TODO: Uncomment when CwcApiV1 is implemented
  Logger,
  type ExpressApi,
  type BackendUtilsConfig,
} from 'cwc-backend-utils';
import type { RuntimeEnvironment } from 'cwc-types';
import type { Request, Response } from 'express';
import type { CwcApiConfig } from './config';
import { loadConfig } from './config';

console.log(`
 █████╗ ██████╗ ██╗
██╔══██╗██╔══██╗██║
███████║██████╔╝██║
██╔══██║██╔═══╝ ██║
██║  ██║██║     ██║
╚═╝  ╚═╝╚═╝     ╚═╝
`);

/**
 * Health check endpoint for load balancers and monitoring
 */
function healthHandler(_req: Request, res: Response): void {
  res.json({
    status: 'healthy',
    service: 'cwc-api',
    timestamp: new Date().toISOString(),
  });
}

/**
 * Converts CwcApiConfig to BackendUtilsConfig for createExpressService
 */
function createBackendUtilsConfig(apiConfig: CwcApiConfig): BackendUtilsConfig {
  return {
    debugMode: apiConfig.debugMode,
    dataUri: apiConfig.dataUri,
    logErrorsToDatabase: apiConfig.logErrorsToDatabase,
    isDev: apiConfig.isDev,
    isTest: apiConfig.isTest,
    isProd: apiConfig.isProd,
    isUnit: apiConfig.isUnit,
    isE2E: apiConfig.isE2E,
    corsOrigin: apiConfig.corsOrigin,
    servicePort: apiConfig.servicePort,
    rateLimiterPoints: apiConfig.rateLimiterPoints,
    rateLimiterDuration: apiConfig.rateLimiterDuration,
    devCorsOrigin: apiConfig.devCorsOrigin,
  };
}

/**
 * Main entry point for the cwc-api microservice
 */
async function main(): Promise<void> {
  try {
    console.log('[cwc-api] Starting cwc-api microservice...');

    // Load environment variables
    loadDotEnv({
      serviceName: 'cwc-api',
      environment: (process.env['RUNTIME_ENVIRONMENT'] as RuntimeEnvironment) || 'dev',
      debug: process.env['DEBUG_MODE'] === 'ON',
    });

    // Load and validate configuration
    const config = loadConfig();

    console.log('[cwc-api] Configuration loaded successfully');

    // Create BackendUtilsConfig for shared utilities
    const backendConfig = createBackendUtilsConfig(config);

    // Create Logger (uses database for error logging)
    const logger = new Logger({ config: backendConfig, serviceName: 'cwc-api' });

    // TODO: Create SqlClient and API instances when CwcApiV1 is implemented
    // const sqlClient = new SqlClient({
    //   config: backendConfig,
    //   enableLogging: config.logErrorsToDatabase,
    //   logger,
    //   clientName: 'cwc-api',
    // });
    // const apis: ExpressApi[] = [healthApi, new CwcApiV1(config, sqlClient, logger)];

    // Health check API
    const healthApi: ExpressApi = {
      version: 1,
      path: '/health/v1',
      handler: healthHandler,
    };

    // APIs - health check always available, CwcApiV1 to be added later
    const apis: ExpressApi[] = [healthApi];

    // Suppress unused variable warning until APIs are implemented
    void logger;

    // Create Express service
    const service = createExpressService({
      config: backendConfig,
      serviceName: 'cwc-api',
      apis,
      allowGet: false,
      allowOptions: true,
      allowPost: true,
      payloadLimit: undefined,
    });

    // Start the service
    service.start(apis);

    console.log('');
    console.log('='.repeat(60));
    console.log(`[cwc-api] Service started successfully`);
    console.log(`[cwc-api] Environment: ${config.runtimeEnvironment}`);
    console.log(`[cwc-api] Port: ${config.servicePort}`);
    console.log(`[cwc-api] Data URI: ${config.dataUri}`);
    console.log(`[cwc-api] Auth URI: ${config.authUri}`);
    console.log(`[cwc-api] Debug: ${config.debugMode ? 'enabled' : 'disabled'}`);
    console.log('='.repeat(60));
    console.log('');

    // Handle graceful shutdown
    const shutdown = async (signal: string): Promise<void> => {
      console.log(`\n[cwc-api] Received ${signal}, shutting down gracefully...`);

      try {
        // Close HTTP server
        await new Promise<void>((resolve, reject) => {
          service.httpServer.close((err) => {
            if (err) {
              reject(err);
            } else {
              resolve();
            }
          });
        });

        console.log('[cwc-api] HTTP server closed');
        console.log('[cwc-api] Shutdown complete');
        process.exit(0);
      } catch (error) {
        console.error('[cwc-api] Error during shutdown:', error);
        process.exit(1);
      }
    };

    // Register shutdown handlers
    process.on('SIGTERM', () => shutdown('SIGTERM'));
    process.on('SIGINT', () => shutdown('SIGINT'));

    // Handle uncaught errors
    process.on('unhandledRejection', async (reason, promise) => {
      console.error('[cwc-api] Unhandled Rejection at:', promise, 'reason:', reason);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        await logger.logError({
          userPkId: undefined,
          codeLocation: 'index.ts:unhandledRejection',
          message: 'Unhandled Rejection',
          error: reason,
        });
      }

      // Don't exit on unhandled rejection in production
      if (!config.isProduction) {
        process.exit(1);
      }
    });

    process.on('uncaughtException', async (error) => {
      console.error('[cwc-api] Uncaught Exception:', error);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        await logger.logError({
          userPkId: undefined,
          codeLocation: 'index.ts:uncaughtException',
          message: 'Uncaught Exception',
          error,
        });
      }

      // Always exit on uncaught exception
      process.exit(1);
    });
  } catch (error) {
    console.error('[cwc-api] Failed to start service:', error);
    process.exit(1);
  }
}

// Start the service
main();

// Export for testing
export { main };

Version 2 (latest)

import {
  loadDotEnv,
  createExpressService,
  // SqlClient, // TODO: Uncomment when CwcApiV1 is implemented
  Logger,
  type ExpressApi,
  type BackendUtilsConfig,
} from 'cwc-backend-utils';
import type { RuntimeEnvironment } from 'cwc-types';
import type { Request, Response } from 'express';
import type { CwcApiConfig } from './config';
import { loadConfig } from './config';

console.log(`
 █████╗ ██████╗ ██╗
██╔══██╗██╔══██╗██║
███████║██████╔╝██║
██╔══██║██╔═══╝ ██║
██║  ██║██║     ██║
╚═╝  ╚═╝╚═╝     ╚═╝
`);

/**
 * Health check endpoint for load balancers and monitoring
 */
function healthHandler(_req: Request, res: Response): void {
  res.json({
    status: 'healthy',
    service: 'cwc-api',
    timestamp: new Date().toISOString(),
  });
}

/**
 * Converts CwcApiConfig to BackendUtilsConfig for createExpressService
 */
function createBackendUtilsConfig(apiConfig: CwcApiConfig): BackendUtilsConfig {
  return {
    debugMode: apiConfig.debugMode,
    dataUri: apiConfig.dataUri,
    logErrorsToDatabase: apiConfig.logErrorsToDatabase,
    isDev: apiConfig.isDev,
    isTest: apiConfig.isTest,
    isProd: apiConfig.isProd,
    isUnit: apiConfig.isUnit,
    isE2E: apiConfig.isE2E,
    corsOrigin: apiConfig.corsOrigin,
    servicePort: apiConfig.servicePort,
    rateLimiterPoints: apiConfig.rateLimiterPoints,
    rateLimiterDuration: apiConfig.rateLimiterDuration,
    devCorsOrigin: apiConfig.devCorsOrigin,
  };
}

/**
 * Main entry point for the cwc-api microservice
 */
async function main(): Promise<void> {
  try {
    console.log('[cwc-api] Starting cwc-api microservice...');

    // Load environment variables
    loadDotEnv({
      serviceName: 'cwc-api',
      environment: (process.env['RUNTIME_ENVIRONMENT'] as RuntimeEnvironment) || 'dev',
      debug: process.env['DEBUG_MODE'] === 'ON',
    });

    // Load and validate configuration
    const config = loadConfig();

    console.log('[cwc-api] Configuration loaded successfully');

    // Create BackendUtilsConfig for shared utilities
    const backendConfig = createBackendUtilsConfig(config);

    // Create Logger (uses database for error logging)
    const logger = new Logger({ config: backendConfig, serviceName: 'cwc-api' });

    // TODO: Create SqlClient and API instances when CwcApiV1 is implemented
    // const sqlClient = new SqlClient({
    //   config: backendConfig,
    //   enableLogging: config.logErrorsToDatabase,
    //   logger,
    //   clientName: 'cwc-api',
    // });
    // const apis: ExpressApi[] = [healthApi, new CwcApiV1(config, sqlClient, logger)];

    // Health check API
    const healthApi: ExpressApi = {
      version: 1,
      path: '/health/v1',
      handler: healthHandler,
    };

    // APIs - health check always available, CwcApiV1 to be added later
    const apis: ExpressApi[] = [healthApi];

    // Suppress unused variable warning until APIs are implemented
    void logger;

    // Create Express service
    const service = createExpressService({
      config: backendConfig,
      serviceName: 'cwc-api',
      apis,
      allowGet: false,
      allowOptions: true,
      allowPost: true,
      payloadLimit: undefined,
    });

    // Start the service
    service.start(apis);

    console.log('');
    console.log('='.repeat(60));
    console.log(`[cwc-api] Service started successfully`);
    console.log(`[cwc-api] Environment: ${config.runtimeEnvironment}`);
    console.log(`[cwc-api] Port: ${config.servicePort}`);
    console.log(`[cwc-api] Data URI: ${config.dataUri}`);
    console.log(`[cwc-api] Auth URI: ${config.authUri}`);
    console.log(`[cwc-api] Debug: ${config.debugMode ? 'enabled' : 'disabled'}`);
    console.log('='.repeat(60));
    console.log('');

    // Handle graceful shutdown
    const shutdown = async (signal: string): Promise<void> => {
      console.log(`\n[cwc-api] Received ${signal}, shutting down gracefully...`);

      try {
        // Close HTTP server
        await new Promise<void>((resolve, reject) => {
          service.httpServer.close((err) => {
            if (err) {
              reject(err);
            } else {
              resolve();
            }
          });
        });

        console.log('[cwc-api] HTTP server closed');
        console.log('[cwc-api] Shutdown complete');
        process.exit(0);
      } catch (error) {
        console.error('[cwc-api] Error during shutdown:', error);
        process.exit(1);
      }
    };

    // Register shutdown handlers
    process.on('SIGTERM', () => shutdown('SIGTERM'));
    process.on('SIGINT', () => shutdown('SIGINT'));

    // Handle uncaught errors
    process.on('unhandledRejection', async (reason, promise) => {
      console.error('[cwc-api] Unhandled Rejection at:', promise, 'reason:', reason);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        await logger.logError({
          userPkId: undefined,
          codeLocation: 'index.ts:unhandledRejection',
          message: 'Unhandled Rejection',
          error: reason,
        });
      }

      // Don't exit on unhandled rejection in production
      if (!config.isProd) {
        process.exit(1);
      }
    });

    process.on('uncaughtException', async (error) => {
      console.error('[cwc-api] Uncaught Exception:', error);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        await logger.logError({
          userPkId: undefined,
          codeLocation: 'index.ts:uncaughtException',
          message: 'Uncaught Exception',
          error,
        });
      }

      // Always exit on uncaught exception
      process.exit(1);
    });
  } catch (error) {
    console.error('[cwc-api] Failed to start service:', error);
    process.exit(1);
  }
}

// Start the service
main();

// Export for testing
export { main };

packages/cwc-auth/src/__tests__/auth.test.ts

2 versions

Version 1

import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import {
  createAuthenticateUser,
  createInvalidateSession,
  createRenewSession,
} from '../auth';
import type { AuthDependencies } from '../auth/auth.types';
import { hashPassword } from '../password';
import { createUserJwt } from '../jwt';
import type { SqlClientType } from 'cwc-backend-utils';
import {
  createMockSqlClient,
  createMockConfig,
  createProductionConfig,
  createDevConfig,
  createMockLogger,
} from './mocks';

describe('Auth Functions', () => {
  let mockSqlClient: jest.Mocked<SqlClientType>;

  beforeEach(() => {
    mockSqlClient = createMockSqlClient();
    jest.clearAllMocks();
  });

  describe('createAuthenticateUser', () => {
    it('should authenticate user with correct credentials', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();
      const hashedPassword = await hashPassword('correctPassword');

      // Mock user query
      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });

      // Mock owned projects query
      mockSqlClient.getFirstResults.mockReturnValueOnce([
        { projectId: 'project-1' },
        { projectId: 'project-2' },
      ]);

      // Mock JWT insert
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'correctPassword',
      });

      expect(result.success).toBe(true);
      if (result.success) {
        expect(result.userPkId).toBe(1);
        expect(result.username).toBe('testuser');
        expect(result.jwt).toBeDefined();
      }
    });

    it('should authenticate with kulo=true', async () => {
      const config = createMockConfig();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'correctPassword',
        kulo: true,
      });

      expect(result.success).toBe(true);
    });

    it('should return MISSING_CREDENTIALS for empty username', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: '',
        password: 'somePassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_CREDENTIALS');
        expect(result.errorDetail).toBeDefined(); // Dev mode
      }
    });

    it('should return MISSING_CREDENTIALS for empty password', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: '',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_CREDENTIALS');
      }
    });

    it('should return USER_NOT_FOUND in development mode when user does not exist', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'nonexistent',
        password: 'somePassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('USER_NOT_FOUND');
        expect(result.errorDetail).toContain('No user found');
      }
    });

    it('should return INVALID_CREDENTIALS in production when user does not exist', async () => {
      const config = createProductionConfig();
      const logger = createMockLogger();

      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'nonexistent',
        password: 'somePassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_CREDENTIALS');
        expect(result.errorDetail).toBeUndefined(); // No details in prod
      }
    });

    it('should return INVALID_PASSWORD in development mode for wrong password', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'wrongPassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_PASSWORD');
      }
    });

    it('should return INVALID_CREDENTIALS in production for wrong password', async () => {
      const config = createProductionConfig();
      const logger = createMockLogger();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'wrongPassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_CREDENTIALS');
        expect(result.errorDetail).toBeUndefined();
      }
    });

    it('should return USER_DISABLED in development for disabled user', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: false, // Disabled user
      });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'correctPassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('USER_DISABLED');
      }
    });

    it('should return JWT_CREATION_FAILED if insert fails', async () => {
      const config = createMockConfig();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getInsertResult.mockReturnValueOnce(false); // Insert fails

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'correctPassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('JWT_CREATION_FAILED');
      }
    });

    it('should perform timing-safe check even when user not found', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      // User not found
      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      // Time the operation - should take similar time as valid user check
      const start = Date.now();
      await authenticateUser({
        username: 'nonexistent',
        password: 'somePassword',
      });
      const elapsed = Date.now() - start;

      // bcrypt should take at least some time (>10ms typically)
      expect(elapsed).toBeGreaterThan(10);
    });

    it('should handle database error gracefully', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      mockSqlClient.query.mockRejectedValueOnce(new Error('Database connection failed'));

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'somePassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
        expect(result.errorDetail).toContain('Database connection failed');
      }
      expect(logger.logError).toHaveBeenCalled();
    });
  });

  describe('createInvalidateSession', () => {
    it('should invalidate a valid session', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      // Create a valid JWT
      const token = createUserJwt(
        {
          jti: 'session-id-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      // Mock session exists
      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      // Mock delete success
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(`Bearer ${token}`);

      expect(result.success).toBe(true);
    });

    it('should return MISSING_TOKEN for missing auth header', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(undefined);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_TOKEN');
      }
    });

    it('should return MISSING_TOKEN for empty auth header', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession('');

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_TOKEN');
      }
    });

    it('should return INVALID_TOKEN for malformed JWT', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession('Bearer not-a-valid-jwt');

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_TOKEN');
      }
    });

    it('should return SESSION_NOT_FOUND if session not in database', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-id-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      // Session not found
      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('SESSION_NOT_FOUND');
      }
    });

    it('should return INTERNAL_ERROR if delete fails', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-id-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getDeleteResult.mockReturnValueOnce(false);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
      }
    });

    it('should handle database error gracefully', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      const token = createUserJwt(
        {
          jti: 'session-id-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.query.mockRejectedValueOnce(new Error('Database error'));

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
      }
      expect(logger.logError).toHaveBeenCalled();
    });
  });

  describe('createRenewSession', () => {
    it('should renew a valid session with fresh claims', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      const token = createUserJwt(
        {
          jti: 'old-session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'old-session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: ['old-project'],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      // Mock session exists
      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      // Mock fresh projects
      mockSqlClient.getFirstResults.mockReturnValueOnce([
        { projectId: 'new-project-1' },
        { projectId: 'new-project-2' },
      ]);
      // Mock delete success
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      // Mock insert success
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(true);
      if (result.success) {
        expect(result.jwt).toBeDefined();
        // New JWT should have different claims
        expect(result.jwt).not.toBe(token);
      }
    });

    it('should preserve kulo flag during renewal', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'old-session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'old-session-id',
            loginType: 'cwc',
            kulo: true, // KULO enabled
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '30d'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(true);
    });

    it('should return MISSING_TOKEN for missing auth header', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(undefined);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_TOKEN');
      }
    });

    it('should return INVALID_TOKEN for malformed JWT', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession('Bearer invalid-jwt');

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_TOKEN');
      }
    });

    it('should return SESSION_NOT_FOUND if session not in database', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('SESSION_NOT_FOUND');
      }
    });

    it('should return SESSION_NOT_FOUND if concurrent renewal (delete fails)', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(false); // Concurrent renewal

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('SESSION_NOT_FOUND');
        expect(result.errorDetail).toContain('concurrent');
      }
    });

    it('should return INTERNAL_ERROR if insert fails after delete', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      mockSqlClient.getInsertResult.mockReturnValueOnce(false); // Insert fails

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
      }
      // Should log critical error
      expect(logger.logError).toHaveBeenCalled();
    });

    it('should handle database error gracefully', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.query.mockRejectedValueOnce(new Error('Database error'));

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
      }
      expect(logger.logError).toHaveBeenCalled();
    });

    it('should query fresh owned projects', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 42,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: ['old-project'],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([
        { projectId: 'fresh-project' },
      ]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      await renewSession(`Bearer ${token}`);

      // Verify selectCommand was called to fetch projects
      expect(mockSqlClient.selectCommand).toHaveBeenCalledWith(
        expect.objectContaining({
          table: 'project',
          filters: expect.objectContaining({ userPkId: 42 }),
        })
      );
    });
  });
});

Version 2 (latest)

import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { createAuthenticateUser, createInvalidateSession, createRenewSession } from '../auth';
import type { AuthDependencies } from '../auth/auth.types';
import { hashPassword } from '../password';
import { createUserJwt } from '../jwt';
import type { SqlClientType } from 'cwc-backend-utils';
import {
  createMockSqlClient,
  createMockConfig,
  createProdConfig,
  createDevConfig,
  createMockLogger,
} from './mocks';

describe('Auth Functions', () => {
  let mockSqlClient: jest.Mocked<SqlClientType>;

  beforeEach(() => {
    mockSqlClient = createMockSqlClient();
    jest.clearAllMocks();
  });

  describe('createAuthenticateUser', () => {
    it('should authenticate user with correct credentials', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();
      const hashedPassword = await hashPassword('correctPassword');

      // Mock user query
      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });

      // Mock owned projects query
      mockSqlClient.getFirstResults.mockReturnValueOnce([
        { projectId: 'project-1' },
        { projectId: 'project-2' },
      ]);

      // Mock JWT insert
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'correctPassword',
      });

      expect(result.success).toBe(true);
      if (result.success) {
        expect(result.userPkId).toBe(1);
        expect(result.username).toBe('testuser');
        expect(result.jwt).toBeDefined();
      }
    });

    it('should authenticate with kulo=true', async () => {
      const config = createMockConfig();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'correctPassword',
        kulo: true,
      });

      expect(result.success).toBe(true);
    });

    it('should return MISSING_CREDENTIALS for empty username', async () => {
      const config = createDevConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: '',
        password: 'somePassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_CREDENTIALS');
        expect(result.errorDetail).toBeDefined(); // Dev mode
      }
    });

    it('should return MISSING_CREDENTIALS for empty password', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: '',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_CREDENTIALS');
      }
    });

    it('should return USER_NOT_FOUND in development mode when user does not exist', async () => {
      const config = createDevConfig();
      const logger = createMockLogger();

      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'nonexistent',
        password: 'somePassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('USER_NOT_FOUND');
        expect(result.errorDetail).toContain('No user found');
      }
    });

    it('should return INVALID_CREDENTIALS in production when user does not exist', async () => {
      const config = createProdConfig();
      const logger = createMockLogger();

      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'nonexistent',
        password: 'somePassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_CREDENTIALS');
        expect(result.errorDetail).toBeUndefined(); // No details in prod
      }
    });

    it('should return INVALID_PASSWORD in development mode for wrong password', async () => {
      const config = createDevConfig();
      const logger = createMockLogger();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'wrongPassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_PASSWORD');
      }
    });

    it('should return INVALID_CREDENTIALS in production for wrong password', async () => {
      const config = createProdConfig();
      const logger = createMockLogger();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'wrongPassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_CREDENTIALS');
        expect(result.errorDetail).toBeUndefined();
      }
    });

    it('should return USER_DISABLED in development for disabled user', async () => {
      const config = createDevConfig();
      const logger = createMockLogger();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: false, // Disabled user
      });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'correctPassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('USER_DISABLED');
      }
    });

    it('should return JWT_CREATION_FAILED if insert fails', async () => {
      const config = createMockConfig();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getInsertResult.mockReturnValueOnce(false); // Insert fails

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'correctPassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('JWT_CREATION_FAILED');
      }
    });

    it('should perform timing-safe check even when user not found', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      // User not found
      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      // Time the operation - should take similar time as valid user check
      const start = Date.now();
      await authenticateUser({
        username: 'nonexistent',
        password: 'somePassword',
      });
      const elapsed = Date.now() - start;

      // bcrypt should take at least some time (>10ms typically)
      expect(elapsed).toBeGreaterThan(10);
    });

    it('should handle database error gracefully', async () => {
      const config = createDevConfig();
      const logger = createMockLogger();

      mockSqlClient.query.mockRejectedValueOnce(new Error('Database connection failed'));

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const authenticateUser = createAuthenticateUser(deps);

      const result = await authenticateUser({
        username: 'testuser',
        password: 'somePassword',
      });

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
        expect(result.errorDetail).toContain('Database connection failed');
      }
      expect(logger.logError).toHaveBeenCalled();
    });
  });

  describe('createInvalidateSession', () => {
    it('should invalidate a valid session', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      // Create a valid JWT
      const token = createUserJwt(
        {
          jti: 'session-id-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      // Mock session exists
      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      // Mock delete success
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(`Bearer ${token}`);

      expect(result.success).toBe(true);
    });

    it('should return MISSING_TOKEN for missing auth header', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(undefined);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_TOKEN');
      }
    });

    it('should return MISSING_TOKEN for empty auth header', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession('');

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_TOKEN');
      }
    });

    it('should return INVALID_TOKEN for malformed JWT', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession('Bearer not-a-valid-jwt');

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_TOKEN');
      }
    });

    it('should return SESSION_NOT_FOUND if session not in database', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-id-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      // Session not found
      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('SESSION_NOT_FOUND');
      }
    });

    it('should return INTERNAL_ERROR if delete fails', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-id-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getDeleteResult.mockReturnValueOnce(false);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
      }
    });

    it('should handle database error gracefully', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      const token = createUserJwt(
        {
          jti: 'session-id-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.query.mockRejectedValueOnce(new Error('Database error'));

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const invalidateSession = createInvalidateSession(deps);

      const result = await invalidateSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
      }
      expect(logger.logError).toHaveBeenCalled();
    });
  });

  describe('createRenewSession', () => {
    it('should renew a valid session with fresh claims', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      const token = createUserJwt(
        {
          jti: 'old-session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'old-session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: ['old-project'],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      // Mock session exists
      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      // Mock fresh projects
      mockSqlClient.getFirstResults.mockReturnValueOnce([
        { projectId: 'new-project-1' },
        { projectId: 'new-project-2' },
      ]);
      // Mock delete success
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      // Mock insert success
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(true);
      if (result.success) {
        expect(result.jwt).toBeDefined();
        // New JWT should have different claims
        expect(result.jwt).not.toBe(token);
      }
    });

    it('should preserve kulo flag during renewal', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'old-session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'old-session-id',
            loginType: 'cwc',
            kulo: true, // KULO enabled
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '30d'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(true);
    });

    it('should return MISSING_TOKEN for missing auth header', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(undefined);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('MISSING_TOKEN');
      }
    });

    it('should return INVALID_TOKEN for malformed JWT', async () => {
      const config = createMockConfig();
      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession('Bearer invalid-jwt');

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INVALID_TOKEN');
      }
    });

    it('should return SESSION_NOT_FOUND if session not in database', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('SESSION_NOT_FOUND');
      }
    });

    it('should return SESSION_NOT_FOUND if concurrent renewal (delete fails)', async () => {
      const config = createDevConfig();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(false); // Concurrent renewal

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('SESSION_NOT_FOUND');
        expect(result.errorDetail).toContain('concurrent');
      }
    });

    it('should return INTERNAL_ERROR if insert fails after delete', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      mockSqlClient.getInsertResult.mockReturnValueOnce(false); // Insert fails

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
      }
      // Should log critical error
      expect(logger.logError).toHaveBeenCalled();
    });

    it('should handle database error gracefully', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.query.mockRejectedValueOnce(new Error('Database error'));

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger };
      const renewSession = createRenewSession(deps);

      const result = await renewSession(`Bearer ${token}`);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.errorCode).toBe('INTERNAL_ERROR');
      }
      expect(logger.logError).toHaveBeenCalled();
    });

    it('should query fresh owned projects', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-id',
          sub: 42,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-id',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: ['old-project'],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([{ projectId: 'fresh-project' }]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSession = createRenewSession(deps);

      await renewSession(`Bearer ${token}`);

      // Verify selectCommand was called to fetch projects
      expect(mockSqlClient.selectCommand).toHaveBeenCalledWith(
        expect.objectContaining({
          table: 'project',
          filters: expect.objectContaining({ userPkId: 42 }),
        })
      );
    });
  });
});

packages/cwc-auth/src/__tests__/config.test.ts

import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';

/**
 * Note: These tests cannot dynamically import loadConfig because the import chain
 * goes through cwc-backend-utils which imports uuid (an ESM module).
 *
 * Instead, we test the key parsing/validation functions directly.
 * The integration of loadConfig is tested via auth.test.ts which uses the config mock.
 */

describe('Configuration Loading', () => {
  let originalEnv: NodeJS.ProcessEnv;
  let exitSpy: jest.SpiedFunction<typeof process.exit>;

  beforeEach(() => {
    // Save original environment
    originalEnv = { ...process.env };

    // Mock process.exit to prevent test termination
    exitSpy = jest.spyOn(process, 'exit').mockImplementation((code?: string | number | null) => {
      throw new Error(`process.exit called with ${code}`);
    }) as jest.SpiedFunction<typeof process.exit>;

    // Clear relevant environment variables
    delete process.env['RUNTIME_ENVIRONMENT'];
    delete process.env['SERVICE_PORT'];
    delete process.env['DATA_URI'];
    delete process.env['APP_URL'];
    delete process.env['CORS_ORIGIN'];
    delete process.env['USER_JWT_SECRET'];
    delete process.env['TEMP_JWT_SECRET'];
    delete process.env['TEMP_JWT_EXPIRES_IN'];
    delete process.env['JWT_USER_EXPIRES_IN'];
    delete process.env['JWT_USER_EXPIRES_IN_KULO'];
    delete process.env['DEBUG_MODE'];
    delete process.env['LOG_ERRORS_TO_DATABASE'];
    delete process.env['RATE_LIMITER_POINTS'];
    delete process.env['RATE_LIMITER_DURATION'];
    delete process.env['DEV_CORS_ORIGIN'];
    delete process.env['SMTP_USE_SANDBOX'];
    delete process.env['SMTP_SANDBOX_ADDRESS'];
    delete process.env['SMTP_SERVICE_NAME'];
    delete process.env['SMTP_AUTH_TYPE'];
    delete process.env['SMTP_SENDER_ADDRESS'];
    delete process.env['SMTP_SENDER_NAME'];
    delete process.env['END_TO_END_TESTING_MOCK_VALUES'];

    // Clear module cache
    jest.resetModules();
  });

  afterEach(() => {
    process.env = originalEnv;
    exitSpy.mockRestore();
  });

  describe('RuntimeEnvironment validation', () => {
    it('should accept valid runtime environments', () => {
      const validEnvs = ['dev', 'test', 'prod', 'unit', 'e2e'];

      for (const env of validEnvs) {
        expect(validEnvs.includes(env)).toBe(true);
      }
    });

    it('should reject invalid runtime environments', () => {
      const invalidEnvs = ['development', 'production', 'invalid', ''];
      const validEnvs = ['dev', 'test', 'prod', 'unit', 'e2e'];

      for (const env of invalidEnvs) {
        expect(validEnvs.includes(env)).toBe(false);
      }
    });
  });

  describe('Secret validation', () => {
    it('should require non-empty secrets', () => {
      const validSecret = 'my-secret-key-for-jwt-signing';
      const invalidSecrets = ['', undefined, null];

      expect(validSecret.length).toBeGreaterThan(0);
      for (const secret of invalidSecrets) {
        expect(!secret || (typeof secret === 'string' && secret.length === 0)).toBe(true);
      }
    });
  });

  describe('Environment boolean derivations', () => {
    it('should correctly derive isProd', () => {
      const tests = [
        { env: 'prod', expected: true },
        { env: 'dev', expected: false },
        { env: 'test', expected: false },
        { env: 'unit', expected: false },
        { env: 'e2e', expected: false },
      ];

      for (const test of tests) {
        const isProd = test.env === 'prod';
        expect(isProd).toBe(test.expected);
      }
    });

    it('should correctly derive isDev', () => {
      const tests = [
        { env: 'dev', expected: true },
        { env: 'prod', expected: false },
        { env: 'test', expected: false },
        { env: 'unit', expected: false },
        { env: 'e2e', expected: false },
      ];

      for (const test of tests) {
        const isDev = test.env === 'dev';
        expect(isDev).toBe(test.expected);
      }
    });

    it('should correctly derive isUnit', () => {
      const tests = [
        { env: 'unit', expected: true },
        { env: 'dev', expected: false },
        { env: 'prod', expected: false },
        { env: 'test', expected: false },
        { env: 'e2e', expected: false },
      ];

      for (const test of tests) {
        const isUnit = test.env === 'unit';
        expect(isUnit).toBe(test.expected);
      }
    });

    it('should correctly derive isE2E', () => {
      const tests = [
        { env: 'e2e', expected: true },
        { env: 'dev', expected: false },
        { env: 'prod', expected: false },
        { env: 'test', expected: false },
        { env: 'unit', expected: false },
      ];

      for (const test of tests) {
        const isE2E = test.env === 'e2e';
        expect(isE2E).toBe(test.expected);
      }
    });
  });

  describe('Port validation', () => {
    it('should accept valid port numbers', () => {
      const validPorts = [1, 80, 443, 3000, 5002, 65535];

      for (const port of validPorts) {
        const isValid = port >= 1 && port <= 65535;
        expect(isValid).toBe(true);
      }
    });

    it('should reject invalid port numbers', () => {
      const invalidPorts = [0, -1, 65536, 99999];

      for (const port of invalidPorts) {
        const isValid = port >= 1 && port <= 65535;
        expect(isValid).toBe(false);
      }
    });
  });

  describe('URL validation', () => {
    it('should accept valid HTTP URLs', () => {
      const validUrls = [
        'http://localhost:3000',
        'http://localhost:5001/data/v1',
        'https://api.example.com',
      ];

      for (const url of validUrls) {
        expect(url.startsWith('http')).toBe(true);
      }
    });

    it('should reject invalid URLs', () => {
      const invalidUrls = ['not-a-url', 'ftp://files.com', '', 'localhost:3000'];

      for (const url of invalidUrls) {
        expect(url.startsWith('http')).toBe(false);
      }
    });
  });

  describe('Default values', () => {
    it('should have correct default JWT expiration values', () => {
      const defaultJwtExpiresIn = '15m';
      const defaultJwtExpiresInKulo = '30d';

      expect(defaultJwtExpiresIn).toBe('15m');
      expect(defaultJwtExpiresInKulo).toBe('30d');
    });

    it('should have correct default rate limiter values', () => {
      const defaultRateLimiterPoints = 15;
      const defaultRateLimiterDuration = 1;

      expect(defaultRateLimiterPoints).toBe(15);
      expect(defaultRateLimiterDuration).toBe(1);
    });
  });
});

packages/cwc-auth/src/__tests__/handlers.test.ts

2 versions

Version 1

import { describe, it, expect, jest } from '@jest/globals';
import { LogonHandler } from '../apis/LogonApiV1/LogonHandler';
import { ServiceHandler } from '../apis/ServiceApiV1/ServiceHandler';
import type { AuthRouteConfig, AuthFunction } from '../apis/LogonApiV1/types';
import type { ServiceRouteConfig, ServiceFunction } from '../apis/ServiceApiV1/types';
import { createMockConfig, createProductionConfig, createDevConfig, createMockLogger } from './mocks';

describe('Handlers', () => {
  describe('LogonHandler', () => {
    it('should return success for logon with JWT', async () => {
      const config = createMockConfig();
      const mockWorker = jest.fn<AuthFunction>().mockResolvedValue({
        success: true,
        jwt: 'test-jwt-token',
        userPkId: 1,
        username: 'testuser',
      });

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logon',
        path: '/logon',
        method: 'POST',
        requiresAuth: false,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: { username: 'test', password: 'pass' }, authHeader: undefined, routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(200);
      expect(result.data.success).toBe(true);
      expect(result.data.jwtType).toBe('user');
      expect(result.jwt).toBe('test-jwt-token');
    });

    it('should return loggedOff=true for logoff success', async () => {
      const config = createMockConfig();
      const mockWorker = jest.fn<AuthFunction>().mockResolvedValue({
        success: true,
      });

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logoff',
        path: '/logoff',
        method: 'POST',
        requiresAuth: true,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: {}, authHeader: 'Bearer token', routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(200);
      expect(result.data.success).toBe(true);
      expect(result.data.loggedOff).toBe(true);
      expect(result.data.jwtType).toBeUndefined();
      expect(result.jwt).toBeUndefined();
    });

    it('should return 401 with error details in dev mode', async () => {
      const config = createMockConfig();
      const mockWorker = jest.fn<AuthFunction>().mockResolvedValue({
        success: false,
        errorCode: 'INVALID_CREDENTIALS',
        errorDetail: 'Invalid password',
      });

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logon',
        path: '/logon',
        method: 'POST',
        requiresAuth: false,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: { username: 'test', password: 'wrong' }, authHeader: undefined, routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBe('INVALID_CREDENTIALS');
      expect(result.data.errorDetail).toBe('Invalid password');
    });

    it('should hide error details in production mode', async () => {
      const config = createProductionConfig();
      const mockWorker = jest.fn<AuthFunction>().mockResolvedValue({
        success: false,
        errorCode: 'USER_NOT_FOUND',
        errorDetail: 'No user found',
      });

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logon',
        path: '/logon',
        method: 'POST',
        requiresAuth: false,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: { username: 'test', password: 'pass' }, authHeader: undefined, routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBeUndefined();
      expect(result.data.errorDetail).toBeUndefined();
    });

    it('should handle worker exception', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();
      const mockWorker = jest.fn<AuthFunction>().mockRejectedValue(new Error('Database error'));

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logon',
        path: '/logon',
        method: 'POST',
        requiresAuth: false,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: {}, authHeader: undefined, routeConfig },
        config,
        logger
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBe('INTERNAL_ERROR');
      expect(result.data.errorDetail).toBe('Database error');
      expect(logger.logError).toHaveBeenCalled();
    });
  });

  describe('ServiceHandler', () => {
    it('should return success with new JWT', async () => {
      const config = createMockConfig();
      const mockWorker = jest.fn<ServiceFunction>().mockResolvedValue({
        success: true,
        jwt: 'new-jwt-token',
      });

      const routeConfig: ServiceRouteConfig = {
        handlerType: 'renew-session',
        path: '/renew-session',
        method: 'POST',
        worker: mockWorker,
      };

      const handler = new ServiceHandler(
        { authHeader: 'Bearer old-token', routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(200);
      expect(result.data.success).toBe(true);
      expect(result.data.jwtType).toBe('user');
      expect(result.jwt).toBe('new-jwt-token');
    });

    it('should return 401 with error details in dev mode', async () => {
      const config = createMockConfig();
      const mockWorker = jest.fn<ServiceFunction>().mockResolvedValue({
        success: false,
        errorCode: 'TOKEN_EXPIRED',
        errorDetail: 'Token has expired',
      });

      const routeConfig: ServiceRouteConfig = {
        handlerType: 'renew-session',
        path: '/renew-session',
        method: 'POST',
        worker: mockWorker,
      };

      const handler = new ServiceHandler(
        { authHeader: 'Bearer expired-token', routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBe('TOKEN_EXPIRED');
      expect(result.data.errorDetail).toBe('Token has expired');
    });

    it('should hide error details in production mode', async () => {
      const config = createProductionConfig();
      const mockWorker = jest.fn<ServiceFunction>().mockResolvedValue({
        success: false,
        errorCode: 'SESSION_NOT_FOUND',
        errorDetail: 'Session was invalidated',
      });

      const routeConfig: ServiceRouteConfig = {
        handlerType: 'renew-session',
        path: '/renew-session',
        method: 'POST',
        worker: mockWorker,
      };

      const handler = new ServiceHandler(
        { authHeader: 'Bearer token', routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBeUndefined();
      expect(result.data.errorDetail).toBeUndefined();
    });

    it('should handle worker exception', async () => {
      const config = createMockConfig();
      const logger = createMockLogger();
      const mockWorker = jest.fn<ServiceFunction>().mockRejectedValue(new Error('Service error'));

      const routeConfig: ServiceRouteConfig = {
        handlerType: 'renew-session',
        path: '/renew-session',
        method: 'POST',
        worker: mockWorker,
      };

      const handler = new ServiceHandler(
        { authHeader: 'Bearer token', routeConfig },
        config,
        logger
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBe('INTERNAL_ERROR');
      expect(logger.logError).toHaveBeenCalled();
    });
  });
});

Version 2 (latest)

import { describe, it, expect, jest } from '@jest/globals';
import { LogonHandler } from '../apis/LogonApiV1/LogonHandler';
import { ServiceHandler } from '../apis/ServiceApiV1/ServiceHandler';
import type { AuthRouteConfig, AuthFunction } from '../apis/LogonApiV1/types';
import type { ServiceRouteConfig, ServiceFunction } from '../apis/ServiceApiV1/types';
import { createMockConfig, createProdConfig, createDevConfig, createMockLogger } from './mocks';

describe('Handlers', () => {
  describe('LogonHandler', () => {
    it('should return success for logon with JWT', async () => {
      const config = createMockConfig();
      const mockWorker = jest.fn<AuthFunction>().mockResolvedValue({
        success: true,
        jwt: 'test-jwt-token',
        userPkId: 1,
        username: 'testuser',
      });

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logon',
        path: '/logon',
        method: 'POST',
        requiresAuth: false,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: { username: 'test', password: 'pass' }, authHeader: undefined, routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(200);
      expect(result.data.success).toBe(true);
      expect(result.data.jwtType).toBe('user');
      expect(result.jwt).toBe('test-jwt-token');
    });

    it('should return loggedOff=true for logoff success', async () => {
      const config = createMockConfig();
      const mockWorker = jest.fn<AuthFunction>().mockResolvedValue({
        success: true,
      });

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logoff',
        path: '/logoff',
        method: 'POST',
        requiresAuth: true,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: {}, authHeader: 'Bearer token', routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(200);
      expect(result.data.success).toBe(true);
      expect(result.data.loggedOff).toBe(true);
      expect(result.data.jwtType).toBeUndefined();
      expect(result.jwt).toBeUndefined();
    });

    it('should return 401 with error details in dev mode', async () => {
      const config = createDevConfig();
      const mockWorker = jest.fn<AuthFunction>().mockResolvedValue({
        success: false,
        errorCode: 'INVALID_CREDENTIALS',
        errorDetail: 'Invalid password',
      });

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logon',
        path: '/logon',
        method: 'POST',
        requiresAuth: false,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: { username: 'test', password: 'wrong' }, authHeader: undefined, routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBe('INVALID_CREDENTIALS');
      expect(result.data.errorDetail).toBe('Invalid password');
    });

    it('should hide error details in production mode', async () => {
      const config = createProdConfig();
      const mockWorker = jest.fn<AuthFunction>().mockResolvedValue({
        success: false,
        errorCode: 'USER_NOT_FOUND',
        errorDetail: 'No user found',
      });

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logon',
        path: '/logon',
        method: 'POST',
        requiresAuth: false,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: { username: 'test', password: 'pass' }, authHeader: undefined, routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBeUndefined();
      expect(result.data.errorDetail).toBeUndefined();
    });

    it('should handle worker exception', async () => {
      const config = createDevConfig();
      const logger = createMockLogger();
      const mockWorker = jest.fn<AuthFunction>().mockRejectedValue(new Error('Database error'));

      const routeConfig: AuthRouteConfig = {
        handlerType: 'logon',
        path: '/logon',
        method: 'POST',
        requiresAuth: false,
        worker: mockWorker,
      };

      const handler = new LogonHandler(
        { payload: {}, authHeader: undefined, routeConfig },
        config,
        logger
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBe('INTERNAL_ERROR');
      expect(result.data.errorDetail).toBe('Database error');
      expect(logger.logError).toHaveBeenCalled();
    });
  });

  describe('ServiceHandler', () => {
    it('should return success with new JWT', async () => {
      const config = createMockConfig();
      const mockWorker = jest.fn<ServiceFunction>().mockResolvedValue({
        success: true,
        jwt: 'new-jwt-token',
      });

      const routeConfig: ServiceRouteConfig = {
        handlerType: 'renew-session',
        path: '/renew-session',
        method: 'POST',
        worker: mockWorker,
      };

      const handler = new ServiceHandler(
        { authHeader: 'Bearer old-token', routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(200);
      expect(result.data.success).toBe(true);
      expect(result.data.jwtType).toBe('user');
      expect(result.jwt).toBe('new-jwt-token');
    });

    it('should return 401 with error details in dev mode', async () => {
      const config = createDevConfig();
      const mockWorker = jest.fn<ServiceFunction>().mockResolvedValue({
        success: false,
        errorCode: 'TOKEN_EXPIRED',
        errorDetail: 'Token has expired',
      });

      const routeConfig: ServiceRouteConfig = {
        handlerType: 'renew-session',
        path: '/renew-session',
        method: 'POST',
        worker: mockWorker,
      };

      const handler = new ServiceHandler(
        { authHeader: 'Bearer expired-token', routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBe('TOKEN_EXPIRED');
      expect(result.data.errorDetail).toBe('Token has expired');
    });

    it('should hide error details in production mode', async () => {
      const config = createProdConfig();
      const mockWorker = jest.fn<ServiceFunction>().mockResolvedValue({
        success: false,
        errorCode: 'SESSION_NOT_FOUND',
        errorDetail: 'Session was invalidated',
      });

      const routeConfig: ServiceRouteConfig = {
        handlerType: 'renew-session',
        path: '/renew-session',
        method: 'POST',
        worker: mockWorker,
      };

      const handler = new ServiceHandler(
        { authHeader: 'Bearer token', routeConfig },
        config,
        undefined
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBeUndefined();
      expect(result.data.errorDetail).toBeUndefined();
    });

    it('should handle worker exception', async () => {
      const config = createDevConfig();
      const logger = createMockLogger();
      const mockWorker = jest.fn<ServiceFunction>().mockRejectedValue(new Error('Service error'));

      const routeConfig: ServiceRouteConfig = {
        handlerType: 'renew-session',
        path: '/renew-session',
        method: 'POST',
        worker: mockWorker,
      };

      const handler = new ServiceHandler(
        { authHeader: 'Bearer token', routeConfig },
        config,
        logger
      );

      const result = await handler.processRequest();

      expect(result.statusCode).toBe(401);
      expect(result.data.success).toBe(false);
      expect(result.data.errorCode).toBe('INTERNAL_ERROR');
      expect(logger.logError).toHaveBeenCalled();
    });
  });
});

packages/cwc-auth/src/__tests__/mocks/config.mock.ts

2 versions

Version 1

'use strict';

import type { CwcAuthConfig } from '../../config/config.types';
import { loadConfig } from '../../config';

/**
 * Gets the real config loaded from unit.cwc-auth.env
 * Use this as the base for test config
 */
export function getTestConfig(): CwcAuthConfig {
  return loadConfig();
}

/**
 * Creates a mock config by applying overrides to the real test config
 * Useful when you need to test specific config variations (e.g., production mode)
 */
export function createMockConfig(overrides?: Partial<CwcAuthConfig>): CwcAuthConfig {
  const baseConfig = loadConfig();
  return { ...baseConfig, ...overrides };
}

/**
 * Creates a production config for testing production error behavior
 * Applies production-like settings while preserving JWT secrets from env
 */
export function createProductionConfig(overrides?: Partial<CwcAuthConfig>): CwcAuthConfig {
  return createMockConfig({
    runtimeEnvironment: 'prod',
    isProd: true,
    isDev: false,
    isTest: false,
    isUnit: false,
    isE2E: false,
    debugMode: false,
    ...overrides,
  });
}

/**
 * Creates a unit test config (should match what's loaded from env)
 * Provided for compatibility with existing tests
 */
export function createUnitTestConfig(overrides?: Partial<CwcAuthConfig>): CwcAuthConfig {
  return createMockConfig({
    runtimeEnvironment: 'unit',
    isProduction: false,
    isDevelopment: false,
    isTest: false,
    isUnitTest: true,
    isEndToEnd: false,
    debugMode: false,
    ...overrides,
  });
}

Version 2 (latest)

'use strict';

import type { CwcAuthConfig } from '../../config/config.types';
import { loadConfig } from '../../config';

/**
 * Gets the real config loaded from unit.cwc-auth.env
 * Use this as the base for test config
 */
export function getTestConfig(): CwcAuthConfig {
  return loadConfig();
}

/**
 * Creates a mock config by applying overrides to the real test config
 * Useful when you need to test specific config variations (e.g., production mode)
 */
export function createMockConfig(overrides?: Partial<CwcAuthConfig>): CwcAuthConfig {
  const baseConfig = loadConfig();
  return { ...baseConfig, ...overrides };
}

/**
 * Creates a production config for testing production error behavior
 * Applies production-like settings while preserving JWT secrets from env
 */
export function createProdConfig(overrides?: Partial<CwcAuthConfig>): CwcAuthConfig {
  return createMockConfig({
    runtimeEnvironment: 'prod',
    isProd: true,
    isDev: false,
    isTest: false,
    isUnit: false,
    isE2E: false,
    debugMode: false,
    ...overrides,
  });
}

/**
 * Creates a unit test config (should match what's loaded from env)
 * Provided for compatibility with existing tests
 */
export function createUnitTestConfig(overrides?: Partial<CwcAuthConfig>): CwcAuthConfig {
  return createMockConfig({
    runtimeEnvironment: 'unit',
    isProd: false,
    isDev: false,
    isTest: false,
    isUnit: true,
    isE2E: false,
    debugMode: false,
    ...overrides,
  });
}

/**
 * Creates a dev config for testing dev-mode behavior
 * Has isDev: true so error details are exposed
 */
export function createDevConfig(overrides?: Partial<CwcAuthConfig>): CwcAuthConfig {
  return createMockConfig({
    runtimeEnvironment: 'dev',
    isProd: false,
    isDev: true,
    isTest: false,
    isUnit: false,
    isE2E: false,
    debugMode: true,
    ...overrides,
  });
}

packages/cwc-auth/src/__tests__/mocks/index.ts

2 versions

Version 1

'use strict';

export { createMockSqlClient } from './sqlClient.mock';
export type {} from './sqlClient.mock';
export {
  mockUserQuerySuccess,
  mockUserQueryNotFound,
  mockOwnedProjectsQuery,
  mockJwtInsertSuccess,
  mockJwtInsertFailure,
  mockSessionDeleteSuccess,
  mockSessionDeleteNotFound,
} from './sqlClient.mock';

export { getTestConfig, createMockConfig, createProductionConfig, createUnitTestConfig, createDevConfig } from './config.mock';

export { createMockLogger } from './logger.mock';

export { WRONG_JWT_SECRET } from './keys.mock';

Version 2 (latest)

'use strict';

export { createMockSqlClient } from './sqlClient.mock';
export type {} from './sqlClient.mock';
export {
  mockUserQuerySuccess,
  mockUserQueryNotFound,
  mockOwnedProjectsQuery,
  mockJwtInsertSuccess,
  mockJwtInsertFailure,
  mockSessionDeleteSuccess,
  mockSessionDeleteNotFound,
} from './sqlClient.mock';

export {
  getTestConfig,
  createMockConfig,
  createProdConfig,
  createUnitTestConfig,
  createDevConfig,
} from './config.mock';

export { createMockLogger } from './logger.mock';

export { WRONG_JWT_SECRET } from './keys.mock';

packages/cwc-auth/src/__tests__/workers.test.ts

2 versions

Version 1

import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { createLogonWorker, createLogoffWorker } from '../apis/LogonApiV1/workers';
import { createRenewSessionWorker, createVerifyTokenWorker } from '../apis/ServiceApiV1/workers';
import type { AuthDependencies } from '../auth/auth.types';
import type { SqlClientType } from 'cwc-backend-utils';
import jwt from 'jsonwebtoken';
import { hashPassword } from '../password';
import { createUserJwt } from '../jwt';
import {
  createMockSqlClient,
  createMockConfig,
  createDevConfig,
  createMockLogger,
  WRONG_JWT_SECRET,
} from './mocks';

describe('Worker Functions', () => {
  let mockSqlClient: jest.Mocked<SqlClientType>;

  beforeEach(() => {
    mockSqlClient = createMockSqlClient();
    jest.clearAllMocks();
  });

  describe('createLogonWorker', () => {
    it('should return success result on valid authentication', async () => {
      const config = createMockConfig();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });
      mockSqlClient.getFirstResults.mockReturnValueOnce([{ projectId: 'proj1' }]);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const logonWorker = createLogonWorker(deps);

      const result = await logonWorker({
        payload: { username: 'testuser', password: 'correctPassword' },
      });

      expect(result.success).toBe(true);
      expect(result.jwt).toBeDefined();
      expect(result.userPkId).toBe(1);
      expect(result.username).toBe('testuser');
    });

    it('should return error result on invalid credentials', async () => {
      const config = createMockConfig();
      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: createMockLogger() };
      const logonWorker = createLogonWorker(deps);

      const result = await logonWorker({
        payload: { username: 'nonexistent', password: 'somepass' },
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('USER_NOT_FOUND');
    });
  });

  describe('createLogoffWorker', () => {
    it('should return success on valid session invalidation', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const logoffWorker = createLogoffWorker(deps);

      const result = await logoffWorker({
        payload: {},
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(true);
    });

    it('should return error for missing token', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const logoffWorker = createLogoffWorker(deps);

      const result = await logoffWorker({
        payload: {},
        authHeader: undefined,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MISSING_TOKEN');
    });
  });

  describe('createRenewSessionWorker', () => {
    it('should return new JWT on successful renewal', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'old-session',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'old-session',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([{ projectId: 'new-proj' }]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSessionWorker = createRenewSessionWorker(deps);

      const result = await renewSessionWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(true);
      expect(result.jwt).toBeDefined();
      expect(result.jwt).not.toBe(token); // New token
    });

    it('should return error for missing token', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSessionWorker = createRenewSessionWorker(deps);

      const result = await renewSessionWorker({
        authHeader: undefined,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MISSING_TOKEN');
    });

    it('should return error for session not found', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'invalid-session',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'invalid-session',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSessionWorker = createRenewSessionWorker(deps);

      const result = await renewSessionWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('SESSION_NOT_FOUND');
    });
  });

  describe('createVerifyTokenWorker', () => {
    it('should return success with payload for valid token', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: ['project-1', 'project-2'],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(true);
      expect(result.payload).toBeDefined();
      expect(result.payload?.sub).toBe(1);
      expect(result.payload?.login.username).toBe('testuser');
      expect(result.payload?.login.ownedProjects).toEqual(['project-1', 'project-2']);
      expect(result.jwt).toBeUndefined(); // verify-token doesn't issue new JWT
    });

    it('should return error for missing Authorization header', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: undefined,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MISSING_TOKEN');
      expect(result.errorDetail).toBe('No token provided in Authorization header');
    });

    it('should return error for invalid Bearer format', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: 'InvalidFormat sometoken',
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MISSING_TOKEN');
    });

    it('should return error for expired token', async () => {
      const config = createMockConfig();

      // Create an expired token manually
      const payload = {
        jti: 'session-123',
        sub: '1',
        iat: Math.floor(Date.now() / 1000) - 3600, // 1 hour ago
        exp: Math.floor(Date.now() / 1000) - 1800, // 30 min ago (expired)
        login: {
          username: 'testuser',
          deviceId: 'device-123',
          userJwtId: 'session-123',
          loginType: 'cwc',
          kulo: false,
          ownedProjects: [],
          isGuestUser: false,
        },
      };

      const expiredToken = jwt.sign(payload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: `Bearer ${expiredToken}`,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('TOKEN_EXPIRED');
    });

    it('should return error for invalid signature', async () => {
      const config = createMockConfig();

      // Create a token with the wrong secret
      const token = createUserJwt(
        {
          jti: 'session-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        WRONG_JWT_SECRET,
        '15m'
      );

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('INVALID_SIGNATURE');
    });

    it('should return error for malformed token', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: 'Bearer not-a-valid-jwt',
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('INVALID_TOKEN');
    });

    it('should return error for malformed payload (missing login claims)', async () => {
      const config = createMockConfig();

      // Create a token with incomplete payload
      const incompletePayload = {
        jti: 'session-123',
        sub: '1',
        iat: Math.floor(Date.now() / 1000),
        exp: Math.floor(Date.now() / 1000) + 900,
        // Missing login claims
      };

      const token = jwt.sign(incompletePayload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MALFORMED_PAYLOAD');
    });
  });
});

Version 2 (latest)

import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { createLogonWorker, createLogoffWorker } from '../apis/LogonApiV1/workers';
import { createRenewSessionWorker, createVerifyTokenWorker } from '../apis/ServiceApiV1/workers';
import type { AuthDependencies } from '../auth/auth.types';
import type { SqlClientType } from 'cwc-backend-utils';
import jwt from 'jsonwebtoken';
import { hashPassword } from '../password';
import { createUserJwt } from '../jwt';
import {
  createMockSqlClient,
  createMockConfig,
  createDevConfig,
  createMockLogger,
  WRONG_JWT_SECRET,
} from './mocks';

describe('Worker Functions', () => {
  let mockSqlClient: jest.Mocked<SqlClientType>;

  beforeEach(() => {
    mockSqlClient = createMockSqlClient();
    jest.clearAllMocks();
  });

  describe('createLogonWorker', () => {
    it('should return success result on valid authentication', async () => {
      const config = createMockConfig();
      const hashedPassword = await hashPassword('correctPassword');

      mockSqlClient.getFirstResult.mockReturnValueOnce({
        userPkId: 1,
        username: 'testuser',
        password: hashedPassword,
        enabled: true,
      });
      mockSqlClient.getFirstResults.mockReturnValueOnce([{ projectId: 'proj1' }]);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const logonWorker = createLogonWorker(deps);

      const result = await logonWorker({
        payload: { username: 'testuser', password: 'correctPassword' },
      });

      expect(result.success).toBe(true);
      expect(result.jwt).toBeDefined();
      expect(result.userPkId).toBe(1);
      expect(result.username).toBe('testuser');
    });

    it('should return error result on invalid credentials', async () => {
      const config = createDevConfig();
      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: createMockLogger() };
      const logonWorker = createLogonWorker(deps);

      const result = await logonWorker({
        payload: { username: 'nonexistent', password: 'somepass' },
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('USER_NOT_FOUND');
    });
  });

  describe('createLogoffWorker', () => {
    it('should return success on valid session invalidation', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const logoffWorker = createLogoffWorker(deps);

      const result = await logoffWorker({
        payload: {},
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(true);
    });

    it('should return error for missing token', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const logoffWorker = createLogoffWorker(deps);

      const result = await logoffWorker({
        payload: {},
        authHeader: undefined,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MISSING_TOKEN');
    });
  });

  describe('createRenewSessionWorker', () => {
    it('should return new JWT on successful renewal', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'old-session',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'old-session',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce({ userJwtPkId: 1 });
      mockSqlClient.getFirstResults.mockReturnValueOnce([{ projectId: 'new-proj' }]);
      mockSqlClient.getDeleteResult.mockReturnValueOnce(true);
      mockSqlClient.getInsertResult.mockReturnValueOnce(true);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSessionWorker = createRenewSessionWorker(deps);

      const result = await renewSessionWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(true);
      expect(result.jwt).toBeDefined();
      expect(result.jwt).not.toBe(token); // New token
    });

    it('should return error for missing token', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSessionWorker = createRenewSessionWorker(deps);

      const result = await renewSessionWorker({
        authHeader: undefined,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MISSING_TOKEN');
    });

    it('should return error for session not found', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'invalid-session',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'invalid-session',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      mockSqlClient.getFirstResult.mockReturnValueOnce(undefined);

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const renewSessionWorker = createRenewSessionWorker(deps);

      const result = await renewSessionWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('SESSION_NOT_FOUND');
    });
  });

  describe('createVerifyTokenWorker', () => {
    it('should return success with payload for valid token', async () => {
      const config = createMockConfig();

      const token = createUserJwt(
        {
          jti: 'session-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: ['project-1', 'project-2'],
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        '15m'
      );

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(true);
      expect(result.payload).toBeDefined();
      expect(result.payload?.sub).toBe(1);
      expect(result.payload?.login.username).toBe('testuser');
      expect(result.payload?.login.ownedProjects).toEqual(['project-1', 'project-2']);
      expect(result.jwt).toBeUndefined(); // verify-token doesn't issue new JWT
    });

    it('should return error for missing Authorization header', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: undefined,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MISSING_TOKEN');
      expect(result.errorDetail).toBe('No token provided in Authorization header');
    });

    it('should return error for invalid Bearer format', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: 'InvalidFormat sometoken',
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MISSING_TOKEN');
    });

    it('should return error for expired token', async () => {
      const config = createMockConfig();

      // Create an expired token manually
      const payload = {
        jti: 'session-123',
        sub: '1',
        iat: Math.floor(Date.now() / 1000) - 3600, // 1 hour ago
        exp: Math.floor(Date.now() / 1000) - 1800, // 30 min ago (expired)
        login: {
          username: 'testuser',
          deviceId: 'device-123',
          userJwtId: 'session-123',
          loginType: 'cwc',
          kulo: false,
          ownedProjects: [],
          isGuestUser: false,
        },
      };

      const expiredToken = jwt.sign(payload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: `Bearer ${expiredToken}`,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('TOKEN_EXPIRED');
    });

    it('should return error for invalid signature', async () => {
      const config = createMockConfig();

      // Create a token with the wrong secret
      const token = createUserJwt(
        {
          jti: 'session-123',
          sub: 1,
          login: {
            username: 'testuser',
            deviceId: 'device-123',
            userJwtId: 'session-123',
            loginType: 'cwc',
            kulo: false,
            ownedProjects: [],
            isGuestUser: false,
          },
        },
        WRONG_JWT_SECRET,
        '15m'
      );

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('INVALID_SIGNATURE');
    });

    it('should return error for malformed token', async () => {
      const config = createMockConfig();

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: 'Bearer not-a-valid-jwt',
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('INVALID_TOKEN');
    });

    it('should return error for malformed payload (missing login claims)', async () => {
      const config = createMockConfig();

      // Create a token with incomplete payload
      const incompletePayload = {
        jti: 'session-123',
        sub: '1',
        iat: Math.floor(Date.now() / 1000),
        exp: Math.floor(Date.now() / 1000) + 900,
        // Missing login claims
      };

      const token = jwt.sign(incompletePayload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const deps: AuthDependencies = { sqlClient: mockSqlClient, config, logger: undefined };
      const verifyTokenWorker = createVerifyTokenWorker(deps);

      const result = await verifyTokenWorker({
        authHeader: `Bearer ${token}`,
      });

      expect(result.success).toBe(false);
      expect(result.errorCode).toBe('MALFORMED_PAYLOAD');
    });
  });
});

packages/cwc-auth/src/apis/LogonApiV1/LogonHandler.ts

'use strict';

import type { ILogger } from 'cwc-backend-utils';
import type {
  AuthRequestPayload,
  AuthRouteConfig,
  AuthRouteHandler,
  AuthRouteHandlerOptions,
  AuthRouteHandlerResponse,
} from './types';
import type { CwcAuthConfig } from '../../config';

const codeLocation = 'apis/LogonApiV1/LogonHandler.ts';

/**
 * Handler for logon/logoff requests
 */
export class LogonHandler implements AuthRouteHandler {
  private payload: AuthRequestPayload;
  private authHeader: string | undefined;
  private routeConfig: AuthRouteConfig;
  private config: CwcAuthConfig;
  private logger: ILogger | undefined;

  constructor(
    options: AuthRouteHandlerOptions,
    config: CwcAuthConfig,
    logger: ILogger | undefined
  ) {
    this.payload = options.payload;
    this.authHeader = options.authHeader;
    this.routeConfig = options.routeConfig;
    this.config = config;
    this.logger = logger;
  }

  /**
   * Processes the auth request
   */
  public async processRequest(): Promise<AuthRouteHandlerResponse> {
    const { path, worker, handlerType } = this.routeConfig;

    try {
      // Execute the worker function
      const result = await worker({
        payload: this.payload,
        authHeader: this.authHeader,
      });

      if (result.success) {
        // Success response
        if (handlerType === 'logoff') {
          return {
            statusCode: 200,
            data: {
              success: true,
              loggedOff: true,
              jwtType: undefined,
            },
            jwt: undefined,
          };
        }

        // Logon success
        return {
          statusCode: 200,
          data: {
            success: true,
            jwtType: 'user',
          },
          jwt: result.jwt,
        };
      }

      // Error response
      const response: AuthRouteHandlerResponse = {
        statusCode: 401,
        data: {
          success: false,
          jwtType: undefined,
        },
        jwt: undefined,
      };

      // Include error details in development mode
      if (this.config.isDev) {
        response.data.errorCode = result.errorCode;
        response.data.errorDetail = result.errorDetail;
      }

      return response;
    } catch (error) {
      this.logger?.logError({
        userPkId: undefined,
        codeLocation,
        message: `Error processing ${path}`,
        error,
      });

      const response: AuthRouteHandlerResponse = {
        statusCode: 401,
        data: {
          success: false,
          jwtType: undefined,
        },
        jwt: undefined,
      };

      if (this.config.isDev) {
        response.data.errorCode = 'INTERNAL_ERROR';
        response.data.errorDetail = error instanceof Error ? error.message : 'Unknown error';
      }

      return response;
    }
  }
}

packages/cwc-auth/src/apis/ServiceApiV1/ServiceHandler.ts

'use strict';

import type { ILogger } from 'cwc-backend-utils';
import type {
  ServiceRouteConfig,
  ServiceRouteHandler,
  ServiceRouteHandlerOptions,
  ServiceRouteHandlerResponse,
} from './types';
import type { CwcAuthConfig } from '../../config';

const codeLocation = 'apis/ServiceApiV1/ServiceHandler.ts';

/**
 * Handler for service requests (renew-session)
 */
export class ServiceHandler implements ServiceRouteHandler {
  private authHeader: string | undefined;
  private routeConfig: ServiceRouteConfig;
  private config: CwcAuthConfig;
  private logger: ILogger | undefined;

  constructor(
    options: ServiceRouteHandlerOptions,
    config: CwcAuthConfig,
    logger: ILogger | undefined
  ) {
    this.authHeader = options.authHeader;
    this.routeConfig = options.routeConfig;
    this.config = config;
    this.logger = logger;
  }

  /**
   * Processes the service request
   */
  public async processRequest(): Promise<ServiceRouteHandlerResponse> {
    const { path, worker } = this.routeConfig;

    try {
      // Execute the worker function
      const result = await worker({
        authHeader: this.authHeader,
      });

      if (result.success) {
        return {
          statusCode: 200,
          data: {
            success: true,
            jwtType: result.jwt ? 'user' : undefined,
            payload: result.payload,
          },
          jwt: result.jwt,
        };
      }

      // Error response
      const response: ServiceRouteHandlerResponse = {
        statusCode: 401,
        data: {
          success: false,
          jwtType: undefined,
        },
        jwt: undefined,
      };

      // Include error details in development mode
      if (this.config.isDev) {
        response.data.errorCode = result.errorCode;
        response.data.errorDetail = result.errorDetail;
      }

      return response;
    } catch (error) {
      this.logger?.logError({
        userPkId: undefined,
        codeLocation,
        message: `Error processing ${path}`,
        error,
      });

      const response: ServiceRouteHandlerResponse = {
        statusCode: 401,
        data: {
          success: false,
          jwtType: undefined,
        },
        jwt: undefined,
      };

      if (this.config.isDev) {
        response.data.errorCode = 'INTERNAL_ERROR';
        response.data.errorDetail = error instanceof Error ? error.message : 'Unknown error';
      }

      return response;
    }
  }
}

packages/cwc-auth/src/auth/createAuthenticateUser.ts

import { v4 as uuidv4 } from 'uuid';
import type { StringValue } from 'ms';
import type {
  AuthDependencies,
  AuthenticateUserResult,
  LogonInput,
  UserQueryResult,
  OwnedProjectQueryResult,
} from './auth.types';
import { verifyPassword } from '../password';
import { createUserJwt } from '../jwt';

const codeLocation = 'auth/createAuthenticateUser.ts';

// SECURITY: Dummy hash for timing-safe password checks when user doesn't exist
// This prevents timing attacks that could reveal valid usernames
// The hash is bcrypt with 12 rounds (same as real passwords)
const DUMMY_PASSWORD_HASH =
  '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/X4.qhF9tJVbJKXW7q';

/**
 * Creates the authenticateUser function with injected dependencies
 *
 * @param deps - Dependencies (sqlClient, config, logger)
 * @returns Function that authenticates a user and returns a JWT
 */
export function createAuthenticateUser(deps: AuthDependencies) {
  const { sqlClient, config, logger } = deps;

  /**
   * Authenticates a user and creates a new session
   *
   * @param input - Logon credentials and options
   * @returns Authentication result with JWT or error
   */
  return async function authenticateUser(
    input: LogonInput
  ): Promise<AuthenticateUserResult> {
    const { username, password, kulo = false } = input;

    // Validate input
    if (!username || !password) {
      return {
        success: false,
        errorCode: 'MISSING_CREDENTIALS',
        errorDetail: config.isDev
          ? 'Username and password are required'
          : undefined,
      };
    }

    try {
      // Query user by username
      const userCommand = sqlClient.selectCommand({
        table: 'user',
        filters: { username },
        fields: ['userPkId', 'username', 'password', 'enabled', 'deviceId', 'loginType'],
      });
      const userResponse = await sqlClient.query({
        userPkId: undefined,
        command: userCommand,
      });
      const user = sqlClient.getFirstResult<UserQueryResult>(userResponse);

      // SECURITY: Timing-safe authentication check
      // Always run bcrypt.compare() even if user doesn't exist
      // This prevents timing attacks that reveal valid usernames
      const hashToVerify = user?.password ?? DUMMY_PASSWORD_HASH;
      const passwordValid = await verifyPassword(password, hashToVerify);

      // Check authentication failure conditions
      // Use generic error in non-dev to prevent user enumeration
      if (!user || !user.enabled || !passwordValid) {
        // Log specific error internally for debugging
        let internalReason = 'Unknown';
        if (!user) {
          internalReason = 'USER_NOT_FOUND';
        } else if (!user.enabled) {
          internalReason = 'USER_DISABLED';
        } else if (!passwordValid) {
          internalReason = 'INVALID_PASSWORD';
        }

        logger?.logInformation({
          userPkId: user?.userPkId,
          codeLocation,
          message: `Authentication failed: ${internalReason}`,
          value: { username },
        });

        // Return generic error to client (specific only in dev mode)
        return {
          success: false,
          errorCode: config.isDev ? internalReason as 'USER_NOT_FOUND' | 'USER_DISABLED' | 'INVALID_PASSWORD' : 'INVALID_CREDENTIALS',
          errorDetail: config.isDev
            ? internalReason === 'USER_NOT_FOUND'
              ? `No user found with username: ${username}`
              : internalReason === 'USER_DISABLED'
                ? 'User account is disabled'
                : 'Password verification failed'
            : undefined,
        };
      }

      // Query owned projects
      const projectsCommand = sqlClient.selectCommand({
        table: 'project',
        filters: { userPkId: user.userPkId, enabled: 1 },
        fields: ['projectId'],
      });
      const projectsResponse = await sqlClient.query({
        userPkId: user.userPkId,
        command: projectsCommand,
      });
      const ownedProjects = sqlClient
        .getFirstResults<OwnedProjectQueryResult>(projectsResponse)
        .map((p) => p.projectId);

      // Generate userJwtId
      const userJwtId = uuidv4();

      // Insert userJwt record (with userPkId for ownership verification)
      const insertCommand = sqlClient.insertCommand({
        table: 'userJwt',
        values: { userJwtId, userPkId: user.userPkId, enabled: 1 },
      });
      const insertResult = await sqlClient.mutate({
        userPkId: user.userPkId,
        command: insertCommand,
      });

      if (!sqlClient.getInsertResult(insertResult)) {
        return {
          success: false,
          errorCode: 'JWT_CREATION_FAILED',
          errorDetail: config.isDev
            ? 'Failed to create user session record'
            : undefined,
        };
      }

      // Create JWT
      const expiresIn = (kulo
        ? config.userJwtExpiresInKulo
        : config.userJwtExpiresIn) as StringValue;

      const jwt = createUserJwt(
        {
          jti: userJwtId,
          sub: user.userPkId,
          login: {
            username: user.username,
            deviceId: user.deviceId,
            userJwtId,
            loginType: user.loginType,
            kulo,
            ownedProjects,
            isGuestUser: false,
          },
        },
        config.secrets.userJwtSecret,
        expiresIn
      );

      // Update user loginDate
      const updateCommand = sqlClient.updateCommand({
        table: 'user',
        filters: { userPkId: user.userPkId },
        values: { loginDate: new Date().toISOString() },
      });
      await sqlClient.mutate({
        userPkId: user.userPkId,
        command: updateCommand,
      });

      if (config.debugMode) {
        logger?.logInformation({
          userPkId: user.userPkId,
          codeLocation,
          message: 'User authenticated successfully',
          value: { username: user.username, kulo, ownedProjects },
        });
      }

      return {
        success: true,
        jwt,
        userPkId: user.userPkId,
        username: user.username,
      };
    } catch (error) {
      logger?.logError({
        userPkId: undefined,
        codeLocation,
        message: 'Authentication error',
        error,
      });

      return {
        success: false,
        errorCode: 'INTERNAL_ERROR',
        errorDetail: config.isDev
          ? error instanceof Error
            ? error.message
            : 'Unknown error'
          : undefined,
      };
    }
  };
}

packages/cwc-auth/src/auth/createInvalidateSession.ts

import type { AuthDependencies, InvalidateSessionResult } from './auth.types';
import { verifyUserJwt, extractJwtFromHeader } from '../jwt';

const codeLocation = 'auth/createInvalidateSession.ts';

/**
 * Creates the invalidateSession function with injected dependencies
 *
 * @param deps - Dependencies (sqlClient, config, logger)
 * @returns Function that invalidates a user session
 */
export function createInvalidateSession(deps: AuthDependencies) {
  const { sqlClient, config, logger } = deps;

  /**
   * Invalidates a user session by deleting the userJwt record
   *
   * @param authHeader - Authorization header value (Bearer <token>)
   * @returns Invalidation result
   */
  return async function invalidateSession(
    authHeader: string | undefined
  ): Promise<InvalidateSessionResult> {
    // Extract token from header
    const token = extractJwtFromHeader(authHeader);
    if (!token) {
      return {
        success: false,
        errorCode: 'MISSING_TOKEN',
        errorDetail: config.isDev
          ? 'Authorization header with Bearer token is required'
          : undefined,
      };
    }

    // Verify JWT
    const verifyResult = verifyUserJwt(token, config.secrets.userJwtSecret);
    if (!verifyResult.success) {
      // SECURITY: In non-dev environments, return generic error to prevent token analysis
      const errorCode = config.isDev
        ? (verifyResult.error === 'TOKEN_EXPIRED' ? 'TOKEN_EXPIRED' : 'INVALID_TOKEN')
        : 'INVALID_TOKEN';

      return {
        success: false,
        errorCode,
        errorDetail: config.isDev
          ? `JWT verification failed: ${verifyResult.error}`
          : undefined,
      };
    }

    const { payload } = verifyResult;

    try {
      // Check if session exists in database
      const selectCommand = sqlClient.selectCommand({
        table: 'userJwt',
        filters: { userJwtId: payload.jti },
        fields: ['userJwtPkId'],
      });
      const selectResult = await sqlClient.query({
        userPkId: payload.sub,
        command: selectCommand,
      });
      const existingSession = sqlClient.getFirstResult<{ userJwtPkId: number }>(selectResult);

      if (!existingSession) {
        return {
          success: false,
          errorCode: 'SESSION_NOT_FOUND',
          errorDetail: config.isDev
            ? 'Session not found in database (may already be invalidated)'
            : undefined,
        };
      }

      // Hard delete the userJwt record (include userPkId for ownership verification)
      const deleteCommand = sqlClient.deleteCommand({
        table: 'userJwt',
        filters: { userJwtId: payload.jti, userPkId: payload.sub },
      });
      const deleteResult = await sqlClient.mutate({
        userPkId: payload.sub,
        command: deleteCommand,
      });

      if (!sqlClient.getDeleteResult(deleteResult)) {
        return {
          success: false,
          errorCode: 'INTERNAL_ERROR',
          errorDetail: config.isDev
            ? 'Failed to delete session record'
            : undefined,
        };
      }

      if (config.debugMode) {
        logger?.logInformation({
          userPkId: payload.sub,
          codeLocation,
          message: 'Session invalidated successfully',
          value: { userJwtId: payload.jti, username: payload.login.username },
        });
      }

      return { success: true };
    } catch (error) {
      logger?.logError({
        userPkId: payload.sub,
        codeLocation,
        message: 'Session invalidation error',
        error,
      });

      return {
        success: false,
        errorCode: 'INTERNAL_ERROR',
        errorDetail: config.isDev
          ? error instanceof Error
            ? error.message
            : 'Unknown error'
          : undefined,
      };
    }
  };
}

packages/cwc-auth/src/auth/createRenewSession.ts

import { v4 as uuidv4 } from 'uuid';
import type { StringValue } from 'ms';
import type {
  AuthDependencies,
  RenewSessionResult,
  OwnedProjectQueryResult,
} from './auth.types';
import { verifyUserJwt, extractJwtFromHeader, createUserJwt } from '../jwt';

const codeLocation = 'auth/createRenewSession.ts';

/**
 * Creates the renewSession function with injected dependencies
 *
 * @param deps - Dependencies (sqlClient, config, logger)
 * @returns Function that renews a user session with fresh claims
 */
export function createRenewSession(deps: AuthDependencies) {
  const { sqlClient, config, logger } = deps;

  /**
   * Renews a user session with fresh claims from database
   * Re-queries owned projects to get updated ownership data
   *
   * @param authHeader - Authorization header value (Bearer <token>)
   * @returns Renewal result with new JWT or error
   */
  return async function renewSession(
    authHeader: string | undefined
  ): Promise<RenewSessionResult> {
    // Extract token from header
    const token = extractJwtFromHeader(authHeader);
    if (!token) {
      return {
        success: false,
        errorCode: 'MISSING_TOKEN',
        errorDetail: config.isDev
          ? 'Authorization header with Bearer token is required'
          : undefined,
      };
    }

    // Verify JWT
    const verifyResult = verifyUserJwt(token, config.secrets.userJwtSecret);
    if (!verifyResult.success) {
      // SECURITY: In non-dev environments, return generic error to prevent token analysis
      const errorCode = config.isDev
        ? (verifyResult.error === 'TOKEN_EXPIRED' ? 'TOKEN_EXPIRED' : 'INVALID_TOKEN')
        : 'INVALID_TOKEN';

      return {
        success: false,
        errorCode,
        errorDetail: config.isDev
          ? `JWT verification failed: ${verifyResult.error}`
          : undefined,
      };
    }

    const { payload } = verifyResult;

    try {
      // Check if session exists in database
      const selectCommand = sqlClient.selectCommand({
        table: 'userJwt',
        filters: { userJwtId: payload.jti },
        fields: ['userJwtPkId'],
      });
      const selectResult = await sqlClient.query({
        userPkId: payload.sub,
        command: selectCommand,
      });
      const existingSession = sqlClient.getFirstResult<{ userJwtPkId: number }>(selectResult);

      if (!existingSession) {
        return {
          success: false,
          errorCode: 'SESSION_NOT_FOUND',
          errorDetail: config.isDev
            ? 'Session not found in database (may already be invalidated)'
            : undefined,
        };
      }

      // Re-query owned projects for fresh data
      const projectsCommand = sqlClient.selectCommand({
        table: 'project',
        filters: { userPkId: payload.sub, enabled: 1 },
        fields: ['projectId'],
      });
      const projectsResponse = await sqlClient.query({
        userPkId: payload.sub,
        command: projectsCommand,
      });
      const ownedProjects = sqlClient
        .getFirstResults<OwnedProjectQueryResult>(projectsResponse)
        .map((p) => p.projectId);

      // SECURITY FIX: Delete-first pattern to prevent race condition
      // Delete old session BEFORE creating new one
      // This prevents multiple valid sessions from concurrent renewal requests
      const deleteCommand = sqlClient.deleteCommand({
        table: 'userJwt',
        filters: { userJwtId: payload.jti, userPkId: payload.sub },
      });
      const deleteResult = await sqlClient.mutate({
        userPkId: payload.sub,
        command: deleteCommand,
      });

      // Verify deletion succeeded (concurrent request would fail here)
      if (!sqlClient.getDeleteResult(deleteResult)) {
        return {
          success: false,
          errorCode: 'SESSION_NOT_FOUND',
          errorDetail: config.isDev
            ? 'Session already invalidated (possible concurrent renewal)'
            : undefined,
        };
      }

      // Generate new userJwtId
      const newUserJwtId = uuidv4();

      // Insert new userJwt record (with userPkId for ownership verification)
      const insertCommand = sqlClient.insertCommand({
        table: 'userJwt',
        values: { userJwtId: newUserJwtId, userPkId: payload.sub, enabled: 1 },
      });
      const insertResult = await sqlClient.mutate({
        userPkId: payload.sub,
        command: insertCommand,
      });

      if (!sqlClient.getInsertResult(insertResult)) {
        // Session was deleted but new one couldn't be created - log this
        logger?.logError({
          userPkId: payload.sub,
          codeLocation,
          message: 'Critical: Old session deleted but new session creation failed',
          error: 'Insert failed after delete',
          value: { oldUserJwtId: payload.jti, newUserJwtId },
        });

        return {
          success: false,
          errorCode: 'INTERNAL_ERROR',
          errorDetail: config.isDev
            ? 'Failed to create new session record'
            : undefined,
        };
      }

      // Create new JWT with fresh ownedProjects (preserve other login claims)
      const expiresIn = (payload.login.kulo
        ? config.userJwtExpiresInKulo
        : config.userJwtExpiresIn) as StringValue;

      const newJwt = createUserJwt(
        {
          jti: newUserJwtId,
          sub: payload.sub,
          login: {
            username: payload.login.username,
            deviceId: payload.login.deviceId,
            userJwtId: newUserJwtId,
            loginType: payload.login.loginType,
            kulo: payload.login.kulo,
            ownedProjects,
            isGuestUser: payload.login.isGuestUser,
          },
        },
        config.secrets.userJwtSecret,
        expiresIn
      );

      if (config.debugMode) {
        logger?.logInformation({
          userPkId: payload.sub,
          codeLocation,
          message: 'Session renewed successfully',
          value: {
            oldUserJwtId: payload.jti,
            newUserJwtId,
            username: payload.login.username,
            ownedProjects,
          },
        });
      }

      return {
        success: true,
        jwt: newJwt,
      };
    } catch (error) {
      logger?.logError({
        userPkId: payload.sub,
        codeLocation,
        message: 'Session renewal error',
        error,
      });

      return {
        success: false,
        errorCode: 'INTERNAL_ERROR',
        errorDetail: config.isDev
          ? error instanceof Error
            ? error.message
            : 'Unknown error'
          : undefined,
      };
    }
  };
}

packages/cwc-auth/src/config/config.types.ts

2 versions

Version 1

import type { RuntimeEnvironment } from 'cwc-types';

/**
 * Secret configuration values for cwc-auth
 * These values must be provided via secrets file, never committed to code
 */
export type CwcAuthConfigSecrets = {
  userJwtSecret: string;
  tempJwtSecret: string;
};

/**
 * Configuration for the cwc-auth microservice
 */
export type CwcAuthConfig = {
  // Environment
  runtimeEnvironment: RuntimeEnvironment;
  isProd: boolean;
  isDev: boolean;
  isTest: boolean;
  isUnit: boolean;
  isE2E: boolean;

  // Service
  name: string;
  servicePort: number;
  dataUri: string;
  appUrl: string;

  // Security
  corsOrigin: string;

  // Rate limiting
  rateLimiterPoints: number;
  rateLimiterDuration: number;

  // Development settings
  devCorsOrigin: string;

  // Debugging
  debugMode: boolean;
  logErrorsToDatabase: boolean;

  // User JWT settings
  userJwtExpiresIn: string;
  userJwtExpiresInKulo: string;

  // temp JWT settings
  tempJwtExpiresIn: string;

  // SMTP settings (for future use)
  smtpUseSandbox: boolean;
  smtpSandboxAddress: string;
  smtpServiceName: string;
  smtpAuthType: string;
  smtpSenderAddress: string;
  smtpSenderName: string;

  // E2E testing
  endToEndMockValues?: Record<string, string> | undefined;

  // Secrets (nested)
  secrets: CwcAuthConfigSecrets;
};

Version 2 (latest)

import type { RuntimeEnvironment } from 'cwc-types';

/**
 * Secret configuration values for cwc-auth
 * These values must be provided via secrets file, never committed to code
 */
export type CwcAuthConfigSecrets = {
  userJwtSecret: string;
  tempJwtSecret: string;
};

/**
 * Configuration for the cwc-auth microservice
 */
export type CwcAuthConfig = {
  // Environment
  runtimeEnvironment: RuntimeEnvironment;
  isProd: boolean;
  isDev: boolean;
  isTest: boolean;
  isUnit: boolean;
  isE2E: boolean;

  // Service
  name: string;
  servicePort: number;
  dataUri: string;
  appUrl: string;

  // Security
  corsOrigin: string;

  // Rate limiting
  rateLimiterPoints: number;
  rateLimiterDuration: number;

  // dev settings
  devCorsOrigin: string;

  // Debugging
  debugMode: boolean;
  logErrorsToDatabase: boolean;

  // User JWT settings
  userJwtExpiresIn: string;
  userJwtExpiresInKulo: string;

  // temp JWT settings
  tempJwtExpiresIn: string;

  // SMTP settings (for future use)
  smtpUseSandbox: boolean;
  smtpSandboxAddress: string;
  smtpServiceName: string;
  smtpAuthType: string;
  smtpSenderAddress: string;
  smtpSenderName: string;

  // E2E testing
  endToEndMockValues?: Record<string, string> | undefined;

  // Secrets (nested)
  secrets: CwcAuthConfigSecrets;
};

packages/cwc-auth/src/config/loadConfig.ts

2 versions

Version 1

import type { RuntimeEnvironment } from 'cwc-types';
import { requireEnv, optionalEnv, parseNumber, parseBoolean, parseJson } from 'cwc-backend-utils';
import type { CwcAuthConfig } from './config.types';

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcAuthConfig | undefined;

export function loadConfig(): CwcAuthConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProd = runtimeEnvironment === 'prod';
    const isDev = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnit = runtimeEnvironment === 'unit';
    const isE2E = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcAuthConfig = {
      // Environment
      runtimeEnvironment,
      isProd,
      isDev,
      isTest,
      isUnit,
      isE2E,

      // Service
      name: 'cwc-auth',
      servicePort: parseNumber('SERVICE_PORT'),
      dataUri: requireEnv('DATA_URI'),
      appUrl: requireEnv('APP_URL'),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),

      // Rate limiting
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 15),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 1),

      // Development settings
      devCorsOrigin: optionalEnv('DEV_CORS_ORIGIN', 'http://localhost:3000'),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE', false),
      logErrorsToDatabase: parseBoolean('LOG_ERRORS_TO_DATABASE', true),

      // User JWT settings
      userJwtExpiresIn: optionalEnv('USER_JWT_EXPIRES_IN', '15m'),
      userJwtExpiresInKulo: optionalEnv('USER_JWT_EXPIRES_IN_KULO', '30d'),

      // Temp JWT settings
      tempJwtExpiresIn: optionalEnv('TEMP_JWT_EXPIRES_IN', '5m'),

      // SMTP settings (for future use)
      smtpUseSandbox: parseBoolean('SMTP_USE_SANDBOX', true),
      smtpSandboxAddress: optionalEnv('SMTP_SANDBOX_ADDRESS', ''),
      smtpServiceName: optionalEnv('SMTP_SERVICE_NAME', ''),
      smtpAuthType: optionalEnv('SMTP_AUTH_TYPE', ''),
      smtpSenderAddress: optionalEnv('SMTP_SENDER_ADDRESS', ''),
      smtpSenderName: optionalEnv('SMTP_SENDER_NAME', ''),

      // E2E testing
      endToEndMockValues: isEndToEnd
        ? parseJson<Record<string, string>>('END_TO_END_TESTING_MOCK_VALUES', undefined)
        : undefined,

      // Secrets (nested)
      secrets: {
        userJwtSecret: requireEnv('USER_JWT_SECRET'),
        tempJwtSecret: requireEnv('TEMP_JWT_SECRET'),
      },
    };

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Validate required URLs
    if (!config.dataUri.startsWith('http')) {
      throw new Error('DATA_URI must be a valid HTTP URL');
    }
    if (!config.appUrl.startsWith('http')) {
      throw new Error('APP_URL must be a valid HTTP URL');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-auth] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  Data URI: ${config.dataUri}`);
      console.log(`  App URL: ${config.appUrl}`);
      console.log(`  CORS Origin: ${config.corsOrigin}`);
      console.log(
        `  Rate Limiter: ${config.rateLimiterPoints} points / ${config.rateLimiterDuration}s`
      );
      console.log(`  User JWT Expires In: ${config.userJwtExpiresIn}`);
      console.log(`  User JWT Expires In (KULO): ${config.userJwtExpiresInKulo}`);
      console.log(`  User JWT Secret: [REDACTED]`);
      console.log(`  Temp JWT Secret: [REDACTED]`);
      console.log(`  Temp JWT Expires In: ${config.tempJwtExpiresIn}`);
      console.log(`  Debug Mode: ${config.debugMode}`);
      console.log(`  Log Errors to Database: ${config.logErrorsToDatabase}`);
    }

    return config;
  } catch (error) {
    console.error('[cwc-auth] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

Version 2 (latest)

import type { RuntimeEnvironment } from 'cwc-types';
import { requireEnv, optionalEnv, parseNumber, parseBoolean, parseJson } from 'cwc-backend-utils';
import type { CwcAuthConfig } from './config.types';

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcAuthConfig | undefined;

export function loadConfig(): CwcAuthConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProd = runtimeEnvironment === 'prod';
    const isDev = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnit = runtimeEnvironment === 'unit';
    const isE2E = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcAuthConfig = {
      // Environment
      runtimeEnvironment,
      isProd,
      isDev,
      isTest,
      isUnit,
      isE2E,

      // Service
      name: 'cwc-auth',
      servicePort: parseNumber('SERVICE_PORT'),
      dataUri: requireEnv('DATA_URI'),
      appUrl: requireEnv('APP_URL'),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),

      // Rate limiting
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 15),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 1),

      // dev settings
      devCorsOrigin: optionalEnv('DEV_CORS_ORIGIN', 'http://localhost:3000'),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE', false),
      logErrorsToDatabase: parseBoolean('LOG_ERRORS_TO_DATABASE', true),

      // User JWT settings
      userJwtExpiresIn: optionalEnv('USER_JWT_EXPIRES_IN', '15m'),
      userJwtExpiresInKulo: optionalEnv('USER_JWT_EXPIRES_IN_KULO', '30d'),

      // Temp JWT settings
      tempJwtExpiresIn: optionalEnv('TEMP_JWT_EXPIRES_IN', '5m'),

      // SMTP settings (for future use)
      smtpUseSandbox: parseBoolean('SMTP_USE_SANDBOX', true),
      smtpSandboxAddress: optionalEnv('SMTP_SANDBOX_ADDRESS', ''),
      smtpServiceName: optionalEnv('SMTP_SERVICE_NAME', ''),
      smtpAuthType: optionalEnv('SMTP_AUTH_TYPE', ''),
      smtpSenderAddress: optionalEnv('SMTP_SENDER_ADDRESS', ''),
      smtpSenderName: optionalEnv('SMTP_SENDER_NAME', ''),

      // E2E testing
      endToEndMockValues: isE2E
        ? parseJson<Record<string, string>>('END_TO_END_TESTING_MOCK_VALUES', undefined)
        : undefined,

      // Secrets (nested)
      secrets: {
        userJwtSecret: requireEnv('USER_JWT_SECRET'),
        tempJwtSecret: requireEnv('TEMP_JWT_SECRET'),
      },
    };

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Validate required URLs
    if (!config.dataUri.startsWith('http')) {
      throw new Error('DATA_URI must be a valid HTTP URL');
    }
    if (!config.appUrl.startsWith('http')) {
      throw new Error('APP_URL must be a valid HTTP URL');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-auth] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  Data URI: ${config.dataUri}`);
      console.log(`  App URL: ${config.appUrl}`);
      console.log(`  CORS Origin: ${config.corsOrigin}`);
      console.log(
        `  Rate Limiter: ${config.rateLimiterPoints} points / ${config.rateLimiterDuration}s`
      );
      console.log(`  User JWT Expires In: ${config.userJwtExpiresIn}`);
      console.log(`  User JWT Expires In (KULO): ${config.userJwtExpiresInKulo}`);
      console.log(`  User JWT Secret: [REDACTED]`);
      console.log(`  Temp JWT Secret: [REDACTED]`);
      console.log(`  Temp JWT Expires In: ${config.tempJwtExpiresIn}`);
      console.log(`  Debug Mode: ${config.debugMode}`);
      console.log(`  Log Errors to Database: ${config.logErrorsToDatabase}`);
    }

    return config;
  } catch (error) {
    console.error('[cwc-auth] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

packages/cwc-auth/src/index.ts

2 versions

Version 1

import {
  loadDotEnv,
  createExpressService,
  SqlClient,
  Logger,
  type ExpressApi,
  type BackendUtilsConfig,
} from 'cwc-backend-utils';
import type { RuntimeEnvironment } from 'cwc-types';
import type { CwcAuthConfig } from './config';
import { loadConfig } from './config';
import { LogonApiV1 } from './apis/LogonApiV1';
import { ServiceApiV1 } from './apis/ServiceApiV1';

console.log(`
  d8888  888     888 88888888888 888    888
 d88888  888     888     888     888    888
d88P888  888     888     888     888    888
d88P 888 888     888     888     8888888888
d88P  888 888     888     888     888    888
d88P   888 888     888     888     888    888
d8888888888 Y88b. .d88P     888     888    888
d88P     888  "Y88888P"      888     888    888
`);

/**
 * Converts CwcAuthConfig to BackendUtilsConfig for createExpressService
 */
function createBackendUtilsConfig(authConfig: CwcAuthConfig): BackendUtilsConfig {
  return {
    debugMode: authConfig.debugMode,
    dataUri: authConfig.dataUri,
    logErrorsToDatabase: authConfig.logErrorsToDatabase,
    isDev: authConfig.isDev,
    isTest: authConfig.isTest,
    isProd: authConfig.isProd,
    isUnit: authConfig.isUnit,
    isE2E: authConfig.isE2E,
    corsOrigin: authConfig.corsOrigin,
    servicePort: authConfig.servicePort,
    rateLimiterPoints: authConfig.rateLimiterPoints,
    rateLimiterDuration: authConfig.rateLimiterDuration,
    devCorsOrigin: authConfig.devCorsOrigin,
  };
}

/**
 * Main entry point for the cwc-auth microservice
 */
async function main(): Promise<void> {
  try {
    console.log('[cwc-auth] Starting cwc-auth microservice...');

    // Load environment variables
    loadDotEnv({
      serviceName: 'cwc-auth',
      environment: (process.env['RUNTIME_ENVIRONMENT'] as RuntimeEnvironment) || 'dev',
      debug: process.env['DEBUG_MODE'] === 'ON',
    });

    // Load and validate configuration
    const config = loadConfig();

    console.log('[cwc-auth] Configuration loaded successfully');

    // Create BackendUtilsConfig for shared utilities
    const backendConfig = createBackendUtilsConfig(config);

    // Create Logger (uses database for error logging)
    const logger = new Logger({ config: backendConfig, serviceName: 'cwc-auth' });

    // Create SqlClient for database operations
    const sqlClient = new SqlClient({
      config: backendConfig,
      enableLogging: config.logErrorsToDatabase,
      logger,
      clientName: 'cwc-auth',
    });

    // Create API instances
    const apis: ExpressApi[] = [
      new LogonApiV1(config, sqlClient, logger),
      new ServiceApiV1(config, sqlClient, logger),
    ];

    // Create Express service
    const service = createExpressService({
      config: backendConfig,
      serviceName: 'cwc-auth',
      apis,
      allowGet: false,
      allowOptions: true,
      allowPost: true,
      payloadLimit: undefined,
    });

    // Start the service
    service.start(apis);

    console.log('');
    console.log('='.repeat(60));
    console.log(`[cwc-auth] Service started successfully`);
    console.log(`[cwc-auth] Environment: ${config.runtimeEnvironment}`);
    console.log(`[cwc-auth] Port: ${config.servicePort}`);
    console.log(`[cwc-auth] Data URI: ${config.dataUri}`);
    console.log(`[cwc-auth] Debug: ${config.debugMode ? 'enabled' : 'disabled'}`);
    console.log('='.repeat(60));
    console.log('');

    // Handle graceful shutdown
    const shutdown = async (signal: string): Promise<void> => {
      console.log(`\n[cwc-auth] Received ${signal}, shutting down gracefully...`);

      try {
        // Close HTTP server
        await new Promise<void>((resolve, reject) => {
          service.httpServer.close((err) => {
            if (err) {
              reject(err);
            } else {
              resolve();
            }
          });
        });

        console.log('[cwc-auth] HTTP server closed');
        console.log('[cwc-auth] Shutdown complete');
        process.exit(0);
      } catch (error) {
        console.error('[cwc-auth] Error during shutdown:', error);
        process.exit(1);
      }
    };

    // Register shutdown handlers
    process.on('SIGTERM', () => shutdown('SIGTERM'));
    process.on('SIGINT', () => shutdown('SIGINT'));

    // Handle uncaught errors
    process.on('unhandledRejection', async (reason, promise) => {
      console.error('[cwc-auth] Unhandled Rejection at:', promise, 'reason:', reason);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        await logger.logError({
          userPkId: undefined,
          codeLocation: 'index.ts:unhandledRejection',
          message: 'Unhandled Rejection',
          error: reason,
        });
      }

      // Don't exit on unhandled rejection in production
      if (!config.isProduction) {
        process.exit(1);
      }
    });

    process.on('uncaughtException', async (error) => {
      console.error('[cwc-auth] Uncaught Exception:', error);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        await logger.logError({
          userPkId: undefined,
          codeLocation: 'index.ts:uncaughtException',
          message: 'Uncaught Exception',
          error,
        });
      }

      // Always exit on uncaught exception
      process.exit(1);
    });
  } catch (error) {
    console.error('[cwc-auth] Failed to start service:', error);
    process.exit(1);
  }
}

// Start the service
main();

// Export for testing
export { main };

Version 2 (latest)

import {
  loadDotEnv,
  createExpressService,
  SqlClient,
  Logger,
  type ExpressApi,
  type BackendUtilsConfig,
} from 'cwc-backend-utils';
import type { RuntimeEnvironment } from 'cwc-types';
import type { CwcAuthConfig } from './config';
import { loadConfig } from './config';
import { LogonApiV1 } from './apis/LogonApiV1';
import { ServiceApiV1 } from './apis/ServiceApiV1';

console.log(`
  d8888  888     888 88888888888 888    888
 d88888  888     888     888     888    888
d88P888  888     888     888     888    888
d88P 888 888     888     888     8888888888
d88P  888 888     888     888     888    888
d88P   888 888     888     888     888    888
d8888888888 Y88b. .d88P     888     888    888
d88P     888  "Y88888P"      888     888    888
`);

/**
 * Converts CwcAuthConfig to BackendUtilsConfig for createExpressService
 */
function createBackendUtilsConfig(authConfig: CwcAuthConfig): BackendUtilsConfig {
  return {
    debugMode: authConfig.debugMode,
    dataUri: authConfig.dataUri,
    logErrorsToDatabase: authConfig.logErrorsToDatabase,
    isDev: authConfig.isDev,
    isTest: authConfig.isTest,
    isProd: authConfig.isProd,
    isUnit: authConfig.isUnit,
    isE2E: authConfig.isE2E,
    corsOrigin: authConfig.corsOrigin,
    servicePort: authConfig.servicePort,
    rateLimiterPoints: authConfig.rateLimiterPoints,
    rateLimiterDuration: authConfig.rateLimiterDuration,
    devCorsOrigin: authConfig.devCorsOrigin,
  };
}

/**
 * Main entry point for the cwc-auth microservice
 */
async function main(): Promise<void> {
  try {
    console.log('[cwc-auth] Starting cwc-auth microservice...');

    // Load environment variables
    loadDotEnv({
      serviceName: 'cwc-auth',
      environment: (process.env['RUNTIME_ENVIRONMENT'] as RuntimeEnvironment) || 'dev',
      debug: process.env['DEBUG_MODE'] === 'ON',
    });

    // Load and validate configuration
    const config = loadConfig();

    console.log('[cwc-auth] Configuration loaded successfully');

    // Create BackendUtilsConfig for shared utilities
    const backendConfig = createBackendUtilsConfig(config);

    // Create Logger (uses database for error logging)
    const logger = new Logger({ config: backendConfig, serviceName: 'cwc-auth' });

    // Create SqlClient for database operations
    const sqlClient = new SqlClient({
      config: backendConfig,
      enableLogging: config.logErrorsToDatabase,
      logger,
      clientName: 'cwc-auth',
    });

    // Create API instances
    const apis: ExpressApi[] = [
      new LogonApiV1(config, sqlClient, logger),
      new ServiceApiV1(config, sqlClient, logger),
    ];

    // Create Express service
    const service = createExpressService({
      config: backendConfig,
      serviceName: 'cwc-auth',
      apis,
      allowGet: false,
      allowOptions: true,
      allowPost: true,
      payloadLimit: undefined,
    });

    // Start the service
    service.start(apis);

    console.log('');
    console.log('='.repeat(60));
    console.log(`[cwc-auth] Service started successfully`);
    console.log(`[cwc-auth] Environment: ${config.runtimeEnvironment}`);
    console.log(`[cwc-auth] Port: ${config.servicePort}`);
    console.log(`[cwc-auth] Data URI: ${config.dataUri}`);
    console.log(`[cwc-auth] Debug: ${config.debugMode ? 'enabled' : 'disabled'}`);
    console.log('='.repeat(60));
    console.log('');

    // Handle graceful shutdown
    const shutdown = async (signal: string): Promise<void> => {
      console.log(`\n[cwc-auth] Received ${signal}, shutting down gracefully...`);

      try {
        // Close HTTP server
        await new Promise<void>((resolve, reject) => {
          service.httpServer.close((err) => {
            if (err) {
              reject(err);
            } else {
              resolve();
            }
          });
        });

        console.log('[cwc-auth] HTTP server closed');
        console.log('[cwc-auth] Shutdown complete');
        process.exit(0);
      } catch (error) {
        console.error('[cwc-auth] Error during shutdown:', error);
        process.exit(1);
      }
    };

    // Register shutdown handlers
    process.on('SIGTERM', () => shutdown('SIGTERM'));
    process.on('SIGINT', () => shutdown('SIGINT'));

    // Handle uncaught errors
    process.on('unhandledRejection', async (reason, promise) => {
      console.error('[cwc-auth] Unhandled Rejection at:', promise, 'reason:', reason);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        await logger.logError({
          userPkId: undefined,
          codeLocation: 'index.ts:unhandledRejection',
          message: 'Unhandled Rejection',
          error: reason,
        });
      }

      // Don't exit on unhandled rejection in production
      if (!config.isProd) {
        process.exit(1);
      }
    });

    process.on('uncaughtException', async (error) => {
      console.error('[cwc-auth] Uncaught Exception:', error);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        await logger.logError({
          userPkId: undefined,
          codeLocation: 'index.ts:uncaughtException',
          message: 'Uncaught Exception',
          error,
        });
      }

      // Always exit on uncaught exception
      process.exit(1);
    });
  } catch (error) {
    console.error('[cwc-auth] Failed to start service:', error);
    process.exit(1);
  }
}

// Start the service
main();

// Export for testing
export { main };

packages/cwc-backend-utils/CLAUDE.md

5 versions

Version 1

cwc-backend-utils Package

Backend utilities for CWC microservices. Node.js-specific utilities only.

Critical Architecture Rule

Only cwc-sql Talks to Database:

✅ All backend services MUST use SqlClient HTTP client
✅ All database operations flow through cwc-sql service via POST /data/v1/command
❌ NEVER import MariaDB or execute SQL from other packages

AuthClient - cwc-auth HTTP Client

Location: src/AuthClient/

HTTP client for cwc-auth service, following same pattern as SqlClient.

Purpose:

Provides typed interface for cwc-auth /verify-token endpoint
Enables services to verify JWTs without duplicating auth logic
Returns simplified VerifyTokenResult for easy consumption

Configuration:

type AuthClientConfig = {
  authUri: string;      // e.g., 'http://localhost:5005/auth/v1'
  timeout?: number;     // Default: 5000ms
};

Usage:

import { AuthClient } from 'cwc-backend-utils';

const authClient = new AuthClient({
  config: { authUri: config.authUri },
  logger: logger,
  clientName: 'cwc-api',
});

const result = await authClient.verifyToken(authHeader);
if (result.success) {
  // result.payload contains UserJwtPayload
} else {
  // result.error contains error code
}

Error Handling:

Missing token → { success: false, error: 'MISSING_TOKEN' }
Invalid/expired token (401) → { success: false, error: 'INVALID_TOKEN' } or specific errorCode
Network/timeout errors → { success: false, error: 'AUTH_SERVICE_ERROR' } + logs error

Design Pattern:

Similar to SqlClient: config + logger + clientName
Graceful degradation: errors don't throw, return typed failure result
Logging: Only logs unexpected errors (network issues, timeouts), not auth failures

JWT Authentication - CRITICAL Security Rules

Token Specifications:

Algorithm: RS256 (RSA public/private key pairs)
Expiration: 30 seconds (short-lived by design)
Auto-refresh: Generate new token when <5s remain before expiry
Payload: { dataJwtId, clientName, exp, iat }

Key File Locations:

Local development: ../../../cwc-secrets/sql-client-api-keys/
Server deployment: ./sql-client-api-keys/

CORS Configuration - Environment-Specific Behavior

Development (isDev: true):

Reflects request origin in Access-Control-Allow-Origin
Allows credentials
Wide open for local development

Test (isTest: true):

Allows devCorsOrigin for localhost development against test services
Falls back to corsOrigin for other requests
Browser security enforces origin headers (cannot be forged)

Production (isProduction: true):

Strict corsOrigin only
No dynamic origins

Rate Limiting Configuration

Configurable via BackendUtilsConfig:

rateLimiterPoints - Max requests per duration (default: 100)
rateLimiterDuration - Time window in seconds (default: 60)
Returns 429 status when exceeded
Memory-based rate limiting per IP

Environment Loading - Data Path Resolution

loadDotEnv Path Resolution:

Local development (dev/unit/e2e):

Path: ../../../../private/cwc-secrets/env/{environment}.{serviceName}.env
Example: ../../../../private/cwc-secrets/env/dev.cwc-api.env

Server deployment (test/prod):

Path: ../../.env.{environment}
Example: ../../.env.test

CRITICAL: Data path pattern MUST include service name to prevent conflicts:

Pattern: {deploymentName}-{serviceName}/data
Example: test-cwc-database/data vs test-mariadb/data

Logger Error Handling

Direct Database Write:

Logger uses SqlClient internally to write to errorLog table
Automatically truncates fields to DB limits (error: 2000 chars, stack: 2000 chars)
Extracts message and stack from Error objects
JSON serializes objects automatically
Tags all logs with serviceName
Debug mode only: logInformation and logDebug output

Express Service Factory - Built-in Middleware

Automatically applies (in order):

Rate Limiter - Memory-based per IP
Helmet - Security headers
CORS - Environment-specific origins
Invalid Routes - Blocks non-registered paths
Error Handling - Captures and logs errors

Invalid Routes Protection:

Rejects HTTP methods not in allowGet/allowPost/allowOptions
Rejects paths that don't start with registered API paths
Returns 400 status with "unsupported" message

Request Utilities

getRemoteIpAddress(req) resolution order:

x-real-ip header (set by nginx proxy)
origin header hostname
req.ip (strips ::ffff: IPv6 prefix if present)

Critical Bugs to Avoid

Environment Variables:

Use process.env['VAR_NAME'] bracket notation (not dot notation)
Use 'dev' not 'development' (matches RuntimeEnvironment type)
Use 'prod' not 'production'

Type Safety:

Extend Express.Request in global namespace, not express-serve-static-core

Configuration Types

BackendUtilsConfig: Complete config with SqlClient/database features

Includes: dataUri, logErrorsToDatabase

BackendUtilsConfigBasic: Simplified config without SqlClient

Omits: dataUri, logErrorsToDatabase
Use for services that don't need database access

Node.js Compatibility

Node.js-only package:

✅ CAN use Node.js APIs (fs, path, crypto, os, http, etc.)
✅ CAN use Node.js-specific packages
❌ NOT browser-compatible
Target: Node.js 22+

Adding New Utilities

Utilities that belong here:

File system operations
Environment configuration helpers
Server-side hashing/crypto
Request/response formatting
Error handling utilities
Logging helpers
JWT utilities
API response builders
Node.js-specific validation

Utilities that DON'T belong here:

Cross-platform utilities → Use cwc-utils
Type definitions → Use cwc-types
Schema definitions → Use cwc-schema
Database queries → Use cwc-database or cwc-sql

Related Packages

Consumed By:

cwc-api, cwc-auth, cwc-admin-api, cwc-sql - All backend microservices

Depends On:

cwc-types (workspace) - Shared TypeScript types

Version 2

cwc-backend-utils Package

Backend utilities for CWC microservices. Node.js-specific utilities only.

Critical Architecture Rule

Only cwc-sql Talks to Database:

✅ All backend services MUST use SqlClient HTTP client
✅ All database operations flow through cwc-sql service via POST /data/v1/command
❌ NEVER import MariaDB or execute SQL from other packages

AuthClient - cwc-auth HTTP Client

Location: src/AuthClient/

HTTP client for cwc-auth service, following same pattern as SqlClient.

Purpose:

Provides typed interface for cwc-auth /verify-token endpoint
Enables services to verify JWTs without duplicating auth logic
Returns simplified VerifyTokenResult for easy consumption

Configuration:

type AuthClientConfig = {
  authUri: string; // e.g., 'http://localhost:5005/auth/v1'
  timeout?: number; // Default: 5000ms
};

Usage:

import { AuthClient } from 'cwc-backend-utils';

const authClient = new AuthClient({
  config: { authUri: config.authUri },
  logger: logger,
  clientName: 'cwc-api',
});

const result = await authClient.verifyToken(authHeader);
if (result.success) {
  // result.payload contains UserJwtPayload
} else {
  // result.error contains error code
}

Error Handling:

Missing token → { success: false, error: 'MISSING_TOKEN' }
Invalid/expired token (401) → { success: false, error: 'INVALID_TOKEN' } or specific errorCode
Network/timeout errors → { success: false, error: 'AUTH_SERVICE_ERROR' } + logs error

Design Pattern:

Similar to SqlClient: config + logger + clientName
Graceful degradation: errors don't throw, return typed failure result
Logging: Only logs unexpected errors (network issues, timeouts), not auth failures

JWT Authentication - CRITICAL Security Rules

Token Specifications:

Algorithm: RS256 (RSA public/private key pairs)
Expiration: 30 seconds (short-lived by design)
Auto-refresh: Generate new token when <5s remain before expiry
Payload: { dataJwtId, clientName, exp, iat }

Key File Locations:

Local development: ../../../cwc-secrets/sql-client-api-keys/
Server deployment: ./sql-client-api-keys/

CORS Configuration - Environment-Specific Behavior

Dev (isDev: true):

Reflects request origin in Access-Control-Allow-Origin
Allows credentials
Wide open for local development

Test (isTest: true):

Allows devCorsOrigin for localhost development against test services
Falls back to corsOrigin for other requests
Browser security enforces origin headers (cannot be forged)

Prod (isProd: true):

Strict corsOrigin only
No dynamic origins

Rate Limiting Configuration

Configurable via BackendUtilsConfig:

rateLimiterPoints - Max requests per duration (default: 100)
rateLimiterDuration - Time window in seconds (default: 60)
Returns 429 status when exceeded
Memory-based rate limiting per IP

Environment Loading - Data Path Resolution

loadDotEnv Path Resolution:

Local development (dev/unit/e2e):

Path: ../../../../private/cwc-secrets/env/{environment}.{serviceName}.env
Example: ../../../../private/cwc-secrets/env/dev.cwc-api.env

Server deployment (test/prod):

Path: ../../.env.{environment}
Example: ../../.env.test

CRITICAL: Data path pattern MUST include service name to prevent conflicts:

Pattern: {deploymentName}-{serviceName}/data
Example: test-cwc-database/data vs test-mariadb/data

Logger Error Handling

Direct Database Write:

Logger uses SqlClient internally to write to errorLog table
Automatically truncates fields to DB limits (error: 2000 chars, stack: 2000 chars)
Extracts message and stack from Error objects
JSON serializes objects automatically
Tags all logs with serviceName
Debug mode only: logInformation and logDebug output

Express Service Factory - Built-in Middleware

Automatically applies (in order):

Rate Limiter - Memory-based per IP
Helmet - Security headers
CORS - Environment-specific origins
Invalid Routes - Blocks non-registered paths
Error Handling - Captures and logs errors

Invalid Routes Protection:

Rejects HTTP methods not in allowGet/allowPost/allowOptions
Rejects paths that don't start with registered API paths
Returns 400 status with "unsupported" message

Request Utilities

getRemoteIpAddress(req) resolution order:

x-real-ip header (set by nginx proxy)
origin header hostname
req.ip (strips ::ffff: IPv6 prefix if present)

Critical Bugs to Avoid

Environment Variables:

Use process.env['VAR_NAME'] bracket notation (not dot notation)
Use 'dev' not 'development' (matches RuntimeEnvironment type)
Use 'prod' not 'production'

Type Safety:

Extend Express.Request in global namespace, not express-serve-static-core

Configuration Types

BackendUtilsConfig: Complete config with SqlClient/database features

Includes: dataUri, logErrorsToDatabase

BackendUtilsConfigBasic: Simplified config without SqlClient

Omits: dataUri, logErrorsToDatabase
Use for services that don't need database access

Node.js Compatibility

Node.js-only package:

✅ CAN use Node.js APIs (fs, path, crypto, os, http, etc.)
✅ CAN use Node.js-specific packages
❌ NOT browser-compatible
Target: Node.js 22+

Adding New Utilities

Utilities that belong here:

File system operations
Environment configuration helpers
Server-side hashing/crypto
Request/response formatting
Error handling utilities
Logging helpers
JWT utilities
API response builders
Node.js-specific validation

Utilities that DON'T belong here:

Cross-platform utilities → Use cwc-utils
Type definitions → Use cwc-types
Schema definitions → Use cwc-schema
Database queries → Use cwc-database or cwc-sql

Related Packages

Consumed By:

cwc-api, cwc-auth, cwc-admin-api, cwc-sql - All backend microservices

Depends On:

cwc-types (workspace) - Shared TypeScript types

Version 3

cwc-backend-utils Package

Backend utilities for CWC microservices. Node.js-specific utilities only.

Critical Architecture Rule

Only cwc-sql Talks to Database:

✅ All backend services MUST use SqlClient HTTP client
✅ All database operations flow through cwc-sql service via POST /data/v1/command
❌ NEVER import MariaDB or execute SQL from other packages

AuthClient - cwc-auth HTTP Client

Location: src/AuthClient/

HTTP client for cwc-auth service, following same pattern as SqlClient.

Purpose:

Provides typed interface for cwc-auth /verify-token endpoint
Enables services to verify JWTs without duplicating auth logic
Returns simplified VerifyTokenResult for easy consumption

Configuration:

type AuthClientConfig = {
  authUri: string; // e.g., 'http://localhost:5005/auth/v1'
  timeout?: number; // Default: 5000ms
};

Usage:

import { AuthClient } from 'cwc-backend-utils';

const authClient = new AuthClient({
  config: { authUri: config.authUri },
  logger: logger,
  clientName: 'cwc-api',
});

const result = await authClient.verifyToken(authHeader);
if (result.success) {
  // result.payload contains UserJwtPayload
} else {
  // result.error contains error code
}

Error Handling:

Missing token → { success: false, error: 'MISSING_TOKEN' }
Invalid/expired token (401) → { success: false, error: 'INVALID_TOKEN' } or specific errorCode
Network/timeout errors → { success: false, error: 'AUTH_SERVICE_ERROR' } + logs error

Design Pattern:

Similar to SqlClient: config + logger + clientName
Graceful degradation: errors don't throw, return typed failure result
Logging: Only logs unexpected errors (network issues, timeouts), not auth failures

JWT Authentication - CRITICAL Security Rules

Token Specifications:

Algorithm: RS256 (RSA public/private key pairs)
Expiration: 30 seconds (short-lived by design)
Auto-refresh: Generate new token when <5s remain before expiry
Payload: { dataJwtId, clientName, exp, iat }

Key File Locations:

Local development: getSecretsSqlClientApiKeysPath() → ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys/
Server deployment: ./sql-client-api-keys/

CORS Configuration - Environment-Specific Behavior

Dev (isDev: true):

Reflects request origin in Access-Control-Allow-Origin
Allows credentials
Wide open for local development

Test (isTest: true):

Allows devCorsOrigin for localhost development against test services
Falls back to corsOrigin for other requests
Browser security enforces origin headers (cannot be forged)

Prod (isProd: true):

Strict corsOrigin only
No dynamic origins

Rate Limiting Configuration

Configurable via BackendUtilsConfig:

rateLimiterPoints - Max requests per duration (default: 100)
rateLimiterDuration - Time window in seconds (default: 60)
Returns 429 status when exceeded
Memory-based rate limiting per IP

Local Secrets Path Functions

Location: src/localSecretsPaths.ts

Centralized path functions for local development secrets using os.homedir().

IMPORTANT: These paths are ONLY used when running locally (dev/unit/e2e). Server deployments (test/prod) use paths relative to the deployment directory.

Functions:

Function	Returns
`getSecretsPath()`	`~/coding-with-claude/private/cwc-secrets`
`getSecretsEnvPath()`	`{base}/env`
`getSecretsSqlClientApiKeysPath()`	`{base}/sql-client-api-keys`
`getSecretsConfigHelperPath()`	`{base}/configuration-helper`
`getSecretsDeploymentPath()`	`{base}/deployment`
`getSecretsEnvFilePath(env, service)`	`{base}/env/{env}.{service}.env`

Usage:

import { getSecretsEnvFilePath, getSecretsSqlClientApiKeysPath } from 'cwc-backend-utils';

// Get .env file path
const envPath = getSecretsEnvFilePath('dev', 'cwc-api');
// Result: /Users/.../coding-with-claude/private/cwc-secrets/env/dev.cwc-api.env

// Get SQL keys path
const keysPath = getSecretsSqlClientApiKeysPath();
// Result: /Users/.../coding-with-claude/private/cwc-secrets/sql-client-api-keys

Environment Loading - loadDotEnv

loadDotEnv Path Resolution:

Local development (dev/unit/e2e):

Uses getSecretsEnvFilePath(environment, serviceName)
Path: ~/coding-with-claude/private/cwc-secrets/env/{environment}.{serviceName}.env

Server deployment (test/prod):

Path: .env.{environment} relative to process.cwd()

CRITICAL: Data path pattern MUST include service name to prevent conflicts:

Pattern: {deploymentName}-{serviceName}/data
Example: test-cwc-database/data vs test-mariadb/data

Logger Error Handling

Direct Database Write:

Logger uses SqlClient internally to write to errorLog table
Automatically truncates fields to DB limits (error: 2000 chars, stack: 2000 chars)
Extracts message and stack from Error objects
JSON serializes objects automatically
Tags all logs with serviceName
Debug mode only: logInformation and logDebug output

Express Service Factory - Built-in Middleware

Automatically applies (in order):

Rate Limiter - Memory-based per IP
Helmet - Security headers
CORS - Environment-specific origins
Invalid Routes - Blocks non-registered paths
Error Handling - Captures and logs errors

Invalid Routes Protection:

Rejects HTTP methods not in allowGet/allowPost/allowOptions
Rejects paths that don't start with registered API paths
Returns 400 status with "unsupported" message

Request Utilities

getRemoteIpAddress(req) resolution order:

x-real-ip header (set by nginx proxy)
origin header hostname
req.ip (strips ::ffff: IPv6 prefix if present)

Critical Bugs to Avoid

Environment Variables:

Use process.env['VAR_NAME'] bracket notation (not dot notation)
Use 'dev' not 'development' (matches RuntimeEnvironment type)
Use 'prod' not 'production'

Type Safety:

Extend Express.Request in global namespace, not express-serve-static-core

Configuration Types

BackendUtilsConfig: Complete config with SqlClient/database features

Includes: dataUri, logErrorsToDatabase

BackendUtilsConfigBasic: Simplified config without SqlClient

Omits: dataUri, logErrorsToDatabase
Use for services that don't need database access

Node.js Compatibility

Node.js-only package:

✅ CAN use Node.js APIs (fs, path, crypto, os, http, etc.)
✅ CAN use Node.js-specific packages
❌ NOT browser-compatible
Target: Node.js 22+

Adding New Utilities

Utilities that belong here:

File system operations
Environment configuration helpers
Server-side hashing/crypto
Request/response formatting
Error handling utilities
Logging helpers
JWT utilities
API response builders
Node.js-specific validation

Utilities that DON'T belong here:

Cross-platform utilities → Use cwc-utils
Type definitions → Use cwc-types
Schema definitions → Use cwc-schema
Database queries → Use cwc-database or cwc-sql

Related Packages

Consumed By:

cwc-api, cwc-auth, cwc-admin-api, cwc-sql - All backend microservices

Depends On:

cwc-types (workspace) - Shared TypeScript types

Version 4

cwc-backend-utils Package

Backend utilities for CWC microservices. Node.js-specific utilities only.

Critical Architecture Rule

Only cwc-sql Talks to Database:

✅ All backend services MUST use SqlClient HTTP client
✅ All database operations flow through cwc-sql service via POST /data/v1/command
❌ NEVER import MariaDB or execute SQL from other packages

AuthClient - cwc-auth HTTP Client

Location: src/AuthClient/

HTTP client for cwc-auth service, following same pattern as SqlClient.

Purpose:

Provides typed interface for cwc-auth /verify-token endpoint
Enables services to verify JWTs without duplicating auth logic
Returns simplified VerifyTokenResult for easy consumption

Configuration:

type AuthClientConfig = {
  authUri: string; // e.g., 'http://localhost:5005/auth/v1'
  timeout?: number; // Default: 5000ms
};

Usage:

import { AuthClient } from 'cwc-backend-utils';

const authClient = new AuthClient({
  config: { authUri: config.authUri },
  logger: logger,
  clientName: 'cwc-api',
});

const result = await authClient.verifyToken(authHeader);
if (result.success) {
  // result.payload contains UserJwtPayload
} else {
  // result.error contains error code
}

Error Handling:

Missing token → { success: false, error: 'MISSING_TOKEN' }
Invalid/expired token (401) → { success: false, error: 'INVALID_TOKEN' } or specific errorCode
Network/timeout errors → { success: false, error: 'AUTH_SERVICE_ERROR' } + logs error

Design Pattern:

Similar to SqlClient: config + logger + clientName
Graceful degradation: errors don't throw, return typed failure result
Logging: Only logs unexpected errors (network issues, timeouts), not auth failures

JWT Authentication - CRITICAL Security Rules

Token Specifications:

Algorithm: RS256 (RSA public/private key pairs)
Expiration: 30 seconds (short-lived by design)
Auto-refresh: Generate new token when <5s remain before expiry
Payload: { dataJwtId, clientName, exp, iat }

Key File Locations:

Local development: getSecretsSqlClientApiKeysPath() → ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys/
Server deployment: ./sql-client-api-keys/

CORS Configuration - Environment-Specific Behavior

Dev (isDev: true):

Reflects request origin in Access-Control-Allow-Origin
Allows credentials
Wide open for local development

Test (isTest: true):

Allows devCorsOrigin for localhost development against test services
Falls back to corsOrigin for other requests
Browser security enforces origin headers (cannot be forged)

Prod (isProd: true):

Strict corsOrigin only
No dynamic origins

Rate Limiting Configuration

Configurable via BackendUtilsConfig:

rateLimiterPoints - Max requests per duration (default: 100)
rateLimiterDuration - Time window in seconds (default: 60)
Returns 429 status when exceeded
Memory-based rate limiting per IP

Local Secrets Path Functions

Location: src/localSecretsPaths.ts

Centralized path functions for local development secrets using os.homedir().

Path Resolution:

Local (dev/unit/e2e): Uses absolute paths via os.homedir() → ~/coding-with-claude/private/cwc-secrets
Server (test/prod): Uses relative paths from deployment directory (e.g., ./sql-client-api-keys)

Functions:

Function	Returns (local)	Returns (server)
`getSecretsPath()`	`~/coding-with-claude/private/cwc-secrets`	N/A (local only)
`getSecretsEnvPath()`	`{base}/env`	N/A (local only)
`getSecretsSqlClientApiKeysPath(runningLocally)`	`{base}/sql-client-api-keys`	`./sql-client-api-keys`
`getSecretsConfigHelperPath(runningLocally)`	`{base}/configuration-helper`	`./configuration-helper`
`getSecretsDeploymentPath(runningLocally)`	`{base}/deployment`	`./deployment`
`getSecretsEnvFilePath(env, service)`	`{base}/env/{env}.{service}.env`	N/A (local only)

Usage:

import { getSecretsEnvFilePath, getSecretsSqlClientApiKeysPath } from 'cwc-backend-utils';

// Get .env file path (local only)
const envPath = getSecretsEnvFilePath('dev', 'cwc-api');
// Result: /Users/.../coding-with-claude/private/cwc-secrets/env/dev.cwc-api.env

// Get SQL keys path (encapsulates local vs server logic)
const runningLocally = config.isDev || config.isUnit || config.isE2E;
const keysPath = getSecretsSqlClientApiKeysPath(runningLocally);
// Local: /Users/.../coding-with-claude/private/cwc-secrets/sql-client-api-keys
// Server: ./sql-client-api-keys

Environment Loading - loadDotEnv

loadDotEnv Path Resolution:

Local development (dev/unit/e2e):

Uses getSecretsEnvFilePath(environment, serviceName)
Path: ~/coding-with-claude/private/cwc-secrets/env/{environment}.{serviceName}.env

Server deployment (test/prod):

Path: .env.{environment} relative to process.cwd()

CRITICAL: Data path pattern MUST include service name to prevent conflicts:

Pattern: {deploymentName}-{serviceName}/data
Example: test-cwc-database/data vs test-mariadb/data

Logger Error Handling

Direct Database Write:

Logger uses SqlClient internally to write to errorLog table
Automatically truncates fields to DB limits (error: 2000 chars, stack: 2000 chars)
Extracts message and stack from Error objects
JSON serializes objects automatically
Tags all logs with serviceName
Debug mode only: logInformation and logDebug output

Express Service Factory - Built-in Middleware

Automatically applies (in order):

Rate Limiter - Memory-based per IP
Helmet - Security headers
CORS - Environment-specific origins
Invalid Routes - Blocks non-registered paths
Error Handling - Captures and logs errors

Invalid Routes Protection:

Rejects HTTP methods not in allowGet/allowPost/allowOptions
Rejects paths that don't start with registered API paths
Returns 400 status with "unsupported" message

Request Utilities

getRemoteIpAddress(req) resolution order:

x-real-ip header (set by nginx proxy)
origin header hostname
req.ip (strips ::ffff: IPv6 prefix if present)

Critical Bugs to Avoid

Environment Variables:

Use process.env['VAR_NAME'] bracket notation (not dot notation)
Use 'dev' not 'development' (matches RuntimeEnvironment type)
Use 'prod' not 'production'

Type Safety:

Extend Express.Request in global namespace, not express-serve-static-core

Configuration Types

BackendUtilsConfig: Complete config with SqlClient/database features

Includes: dataUri, logErrorsToDatabase

BackendUtilsConfigBasic: Simplified config without SqlClient

Omits: dataUri, logErrorsToDatabase
Use for services that don't need database access

Node.js Compatibility

Node.js-only package:

✅ CAN use Node.js APIs (fs, path, crypto, os, http, etc.)
✅ CAN use Node.js-specific packages
❌ NOT browser-compatible
Target: Node.js 22+

Adding New Utilities

Utilities that belong here:

File system operations
Environment configuration helpers
Server-side hashing/crypto
Request/response formatting
Error handling utilities
Logging helpers
JWT utilities
API response builders
Node.js-specific validation

Utilities that DON'T belong here:

Cross-platform utilities → Use cwc-utils
Type definitions → Use cwc-types
Schema definitions → Use cwc-schema
Database queries → Use cwc-database or cwc-sql

Related Packages

Consumed By:

cwc-api, cwc-auth, cwc-admin-api, cwc-sql - All backend microservices

Depends On:

cwc-types (workspace) - Shared TypeScript types

Version 5 (latest)

cwc-backend-utils Package

Backend utilities for CWC microservices. Node.js-specific utilities only.

Critical Architecture Rule

Only cwc-sql Talks to Database:

✅ All backend services MUST use SqlClient HTTP client
✅ All database operations flow through cwc-sql service via POST /data/v1/command
❌ NEVER import MariaDB or execute SQL from other packages

AuthClient - cwc-auth HTTP Client

Location: src/AuthClient/

HTTP client for cwc-auth service, following same pattern as SqlClient.

Purpose:

Provides typed interface for cwc-auth /verify-token endpoint
Enables services to verify JWTs without duplicating auth logic
Returns simplified VerifyTokenResult for easy consumption

Configuration:

type AuthClientConfig = {
  authUri: string; // e.g., 'http://localhost:5005/auth/v1'
  timeout?: number; // Default: 5000ms
};

Usage:

import { AuthClient } from 'cwc-backend-utils';

const authClient = new AuthClient({
  config: { authUri: config.authUri },
  logger: logger,
  clientName: 'cwc-api',
});

const result = await authClient.verifyToken(authHeader);
if (result.success) {
  // result.payload contains UserJwtPayload
} else {
  // result.error contains error code
}

Error Handling:

Missing token → { success: false, error: 'MISSING_TOKEN' }
Invalid/expired token (401) → { success: false, error: 'INVALID_TOKEN' } or specific errorCode
Network/timeout errors → { success: false, error: 'AUTH_SERVICE_ERROR' } + logs error

Design Pattern:

Similar to SqlClient: config + logger + clientName
Graceful degradation: errors don't throw, return typed failure result
Logging: Only logs unexpected errors (network issues, timeouts), not auth failures

JWT Authentication - CRITICAL Security Rules

Token Specifications:

Algorithm: RS256 (RSA public/private key pairs)
Expiration: 30 seconds (short-lived by design)
Auto-refresh: Generate new token when <5s remain before expiry
Payload: { dataJwtId, clientName, exp, iat }

Key File Locations:

Local development: getSecretsSqlClientApiKeysPath() → ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys/
Server deployment: ./sql-client-api-keys/

CORS Configuration - Environment-Specific Behavior

Dev (isDev: true):

Reflects request origin in Access-Control-Allow-Origin
Allows credentials
Wide open for local development

Test (isTest: true):

Allows devCorsOrigin for localhost development against test services
Falls back to corsOrigin for other requests
Browser security enforces origin headers (cannot be forged)

Prod (isProd: true):

Strict corsOrigin only
No dynamic origins

Rate Limiting Configuration

Configurable via BackendUtilsConfig:

rateLimiterPoints - Max requests per duration (default: 100)
rateLimiterDuration - Time window in seconds (default: 60)
Returns 429 status when exceeded
Memory-based rate limiting per IP

Local Secrets Path Functions

Location: src/localSecretsPaths.ts

Centralized path functions for local development secrets using os.homedir().

Path Resolution:

Local (dev/unit/e2e): Uses absolute paths via os.homedir() → ~/coding-with-claude/private/cwc-secrets
Server (test/prod): Uses relative paths from deployment directory (e.g., ./sql-client-api-keys)

Functions:

Function	Returns (local)	Returns (server)
`getSecretsPath()`	`~/coding-with-claude/private/cwc-secrets`	N/A (local only)
`getSecretsEnvPath()`	`{base}/env`	N/A (local only)
`getSecretsSqlClientApiKeysPath(runningLocally)`	`{base}/sql-client-api-keys`	`./sql-client-api-keys`
`getSecretsConfigHelperPath(runningLocally)`	`{base}/configuration-helper`	`./configuration-helper`
`getSecretsDeploymentPath(runningLocally)`	`{base}/deployment`	`./deployment`
`getSecretsEnvFilePath(runningLocally, env, service)`	`{base}/env/{env}.{service}.env`	`.env.{env}`

Usage:

import { getSecretsEnvFilePath, getSecretsSqlClientApiKeysPath } from 'cwc-backend-utils';

const runningLocally = config.isDev || config.isUnit || config.isE2E;

// Get .env file path (encapsulates local vs server logic)
const envPath = getSecretsEnvFilePath(runningLocally, 'dev', 'cwc-api');
// Local: /Users/.../coding-with-claude/private/cwc-secrets/env/dev.cwc-api.env
// Server: .env.dev

// Get SQL keys path (encapsulates local vs server logic)
const keysPath = getSecretsSqlClientApiKeysPath(runningLocally);
// Local: /Users/.../coding-with-claude/private/cwc-secrets/sql-client-api-keys
// Server: ./sql-client-api-keys

Environment Loading - loadDotEnv

loadDotEnv Path Resolution:

Local development (dev/unit/e2e):

Uses getSecretsEnvFilePath(environment, serviceName)
Path: ~/coding-with-claude/private/cwc-secrets/env/{environment}.{serviceName}.env

Server deployment (test/prod):

Path: .env.{environment} relative to process.cwd()

CRITICAL: Data path pattern MUST include service name to prevent conflicts:

Pattern: {deploymentName}-{serviceName}/data
Example: test-cwc-database/data vs test-mariadb/data

Logger Error Handling

Direct Database Write:

Logger uses SqlClient internally to write to errorLog table
Automatically truncates fields to DB limits (error: 2000 chars, stack: 2000 chars)
Extracts message and stack from Error objects
JSON serializes objects automatically
Tags all logs with serviceName
Debug mode only: logInformation and logDebug output

Express Service Factory - Built-in Middleware

Automatically applies (in order):

Rate Limiter - Memory-based per IP
Helmet - Security headers
CORS - Environment-specific origins
Invalid Routes - Blocks non-registered paths
Error Handling - Captures and logs errors

Invalid Routes Protection:

Rejects HTTP methods not in allowGet/allowPost/allowOptions
Rejects paths that don't start with registered API paths
Returns 400 status with "unsupported" message

Request Utilities

getRemoteIpAddress(req) resolution order:

x-real-ip header (set by nginx proxy)
origin header hostname
req.ip (strips ::ffff: IPv6 prefix if present)

Critical Bugs to Avoid

Environment Variables:

Use process.env['VAR_NAME'] bracket notation (not dot notation)
Use 'dev' not 'development' (matches RuntimeEnvironment type)
Use 'prod' not 'production'

Type Safety:

Extend Express.Request in global namespace, not express-serve-static-core

Configuration Types

BackendUtilsConfig: Complete config with SqlClient/database features

Includes: dataUri, logErrorsToDatabase

BackendUtilsConfigBasic: Simplified config without SqlClient

Omits: dataUri, logErrorsToDatabase
Use for services that don't need database access

Node.js Compatibility

Node.js-only package:

✅ CAN use Node.js APIs (fs, path, crypto, os, http, etc.)
✅ CAN use Node.js-specific packages
❌ NOT browser-compatible
Target: Node.js 22+

Adding New Utilities

Utilities that belong here:

File system operations
Environment configuration helpers
Server-side hashing/crypto
Request/response formatting
Error handling utilities
Logging helpers
JWT utilities
API response builders
Node.js-specific validation

Utilities that DON'T belong here:

Cross-platform utilities → Use cwc-utils
Type definitions → Use cwc-types
Schema definitions → Use cwc-schema
Database queries → Use cwc-database or cwc-sql

Related Packages

Consumed By:

cwc-api, cwc-auth, cwc-admin-api, cwc-sql - All backend microservices

Depends On:

cwc-types (workspace) - Shared TypeScript types

packages/cwc-backend-utils/src/backendUtils.types.ts

import http from 'node:http';
import { RequestHandler } from 'express';
import express from 'express';

export type BackendServiceName = 'cwc-admin-api' | 'cwc-api' | 'cwc-auth' | 'cwc-sql' | 'cwc-storage';

export type BackendUtilsConfig = {
  debugMode: boolean;
  dataUri: string;
  logErrorsToDatabase: boolean;
  isDev: boolean;
  isTest: boolean;
  isProd: boolean;
  isUnit: boolean;
  isE2E: boolean;
  corsOrigin: string;
  servicePort: number;
  rateLimiterPoints: number;
  rateLimiterDuration: number;
  // development settings
  devCorsOrigin: string;
  // End-to-end testing mock values
  endToEndMockValues?: Record<string, string> | undefined;
};

// Simplified config for services that don't use SqlClient or database logging
export type BackendUtilsConfigBasic = Omit<BackendUtilsConfig, 'dataUri' | 'logErrorsToDatabase'>;

// *********************************
// SqlClient
// *********************************

export type SqlClientToken = string;

export type SqlClientOperationType = 'delete' | 'insert' | 'select' | 'update';

export type SqlClientOperationName = string;
export type SqlClientOperationTable = string;

export type SqlClientOperationFilters = {
  [key: string]: string | number | boolean | number[];
};

export type SqlClientOperationFields = string[] | undefined;

export type SqlClientOperationValues = {
  [key: string]: string | number | boolean | undefined | unknown | unknown[];
};

export type SqlClientOperationSortItem = {
  fieldName: string;
  direction?: string;
};

export type SqlClientOperationSort = SqlClientOperationSortItem[];

export type SqlClientOperationLimit = {
  recordCount: number;
  startIndex: number;
};

export type SqlClientOperationCustomSql = string;

export type SqlClientOperationCustomParam = string | number | boolean;

export type SqlClientOperationCustomParams = {
  [key: string]: SqlClientOperationCustomParam;
};

// **********************************
// sort example:
// **********************************
// const sort = [ {fieldName: 'username', direction: 'ASC' }, {fieldName: 'groupName', direction: 'DESC' }];

export type SqlClientOperationCustom = {
  customSql: SqlClientOperationCustomSql;
  customParams: SqlClientOperationCustomParams;
  customTables: SqlClientOperationTable[];
};

export type SqlClientOperation = {
  operationType: SqlClientOperationType;
  name?: SqlClientOperationName | undefined;
  table: SqlClientOperationTable | undefined;
  fields?: SqlClientOperationFields | undefined;
  filters?: SqlClientOperationFilters | undefined;
  values?: SqlClientOperationValues | undefined;
  sort?: SqlClientOperationSort | undefined;
  limit?: SqlClientOperationLimit | undefined;
  custom?: SqlClientOperationCustom | undefined;
  filterCount?: boolean | undefined; // return a count of records matching filters
};

export type SqlClientSchemaOptions = {
  userPkId: number | undefined;
};

export type Schema = {
  [key: string]: object;
};

export type SqlClientSchemaResponse = {
  data: Schema;
};

export type SqlClientCommand = {
  transaction: boolean;
  operations: SqlClientOperation[];
  filterCount: boolean; // return filtered record count with results
};

export type SqlClientExecuteOptions = {
  userPkId: number | undefined;
  command: SqlClientCommand;
};

export interface SqlClientQueryResponse {
  [key: string]: unknown[] | undefined;
}

export type SqlClientMutationResult = {
  affectedRows?: number;
  insertId?: number;
  changedRows?: number;
};

export interface SqlClientMutationResponse {
  [key: string]: SqlClientMutationResult;
}

export type SqlClientExecuteQuery = (
  options: SqlClientExecuteOptions
) => Promise<SqlClientQueryResponse | undefined>;

export type SqlClientExecuteMutation = (
  options: SqlClientExecuteOptions
) => Promise<SqlClientMutationResponse | undefined>;

export type VerifySqlClientCredentialsOptions = {
  userPkId: number | undefined;
  authToken: string | undefined;
  invokedBy: string;
};

export type DeleteCommandOptions = Omit<
  SqlClientOperation,
  'operationType' | 'fields' | 'values' | 'sort' | 'limit' | 'custom'
>;

export type InsertCommandOptions = Omit<
  SqlClientOperation,
  'operationType' | 'fields' | 'filters' | 'sort' | 'limit' | 'custom'
>;

export type SelectCommandOptions = Omit<SqlClientOperation, 'operationType' | 'values'>;

export type UpdateCommandOptions = Omit<
  SqlClientOperation,
  'operationType' | 'fields' | 'sort' | 'limit' | 'custom'
>;

export type OperationDetails = Omit<SqlClientOperation, 'table' | 'operationType'>;

export type AddOperationOptions = {
  command: SqlClientCommand;
  table: string | undefined;
  operationType: SqlClientOperationType;
  operationDetails: OperationDetails;
};

export type SqlClientType = {
  query: ({
    userPkId,
    command,
  }: SqlClientExecuteOptions) => Promise<SqlClientQueryResponse | undefined>;
  mutate: ({
    userPkId,
    command,
  }: SqlClientExecuteOptions) => Promise<SqlClientMutationResponse | undefined>;

  getFirstResult: <ResultType>(
    response: SqlClientQueryResponse | undefined
  ) => ResultType | undefined;

  getSecondResult: <ResultType>(
    response: SqlClientQueryResponse | undefined
  ) => ResultType | undefined;

  getResult: <ResultType>(
    response: SqlClientQueryResponse | undefined,
    name: string,
    index: number
  ) => ResultType | undefined;

  getFirstResults: <ResultType>(response: SqlClientQueryResponse | undefined) => ResultType[];

  getSecondResults: <ResultType>(response: SqlClientQueryResponse | undefined) => ResultType[];

  getResults: <ResultType>(
    response: SqlClientQueryResponse | undefined,
    name: string
  ) => ResultType[];

  getInsertResult: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => boolean;

  getInsertResultId: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => number | undefined;

  getUpdateResult: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => boolean;

  getDeleteResult: (
    response: SqlClientMutationResponse | undefined,
    operationName?: string
  ) => boolean;

  emptyCommand: (transaction: boolean) => SqlClientCommand;

  deleteCommand: ({ name, table, filters }: DeleteCommandOptions) => SqlClientCommand;

  insertCommand: ({ name, table, values }: InsertCommandOptions) => SqlClientCommand;

  selectCommand: ({
    name,
    table,
    filters,
    fields,
    sort,
    limit,
    custom,
    filterCount,
  }: SelectCommandOptions) => SqlClientCommand;

  updateCommand: ({ name, table, filters, values }: UpdateCommandOptions) => SqlClientCommand;

  addOperation: ({
    command,
    table,
    operationType,
    operationDetails,
  }: AddOperationOptions) => SqlClientOperation | undefined;
};

// *********************************
// Logger
// *********************************

export interface ILogger {
  logDebug: ({ codeLocation, message, value }: LogDebugOptions) => void;
  logError: ({ codeLocation, message, error, value, request }: LogErrorOptions) => Promise<void>;
  logInformation: ({ codeLocation, message, value }: LogInformationOptions) => void;
}

export type LogErrorOptions = {
  userPkId: number | undefined;
  codeLocation: string;
  message: string;
  error?: unknown | Error | object | string;
  value?: object | string | unknown;
  request?: string | unknown;
};

export type LogInformationOptions = {
  userPkId: number | undefined;
  codeLocation: string;
  message: string;
  value?: object | string;
  request?: string | unknown;
};

export type LogDebugOptions = {
  userPkId: number | undefined;
  codeLocation: string;
  message: string;
  value?: object | string;
  request?: string | unknown;
};

// *********************************
// express
// *********************************

export interface ExpressApi {
  version: number;
  handler: RequestHandler;
  path: string;
}

export type ExpressCorsOptions = {
  config: BackendUtilsConfig;
  allowPost: boolean;
  allowOptions: boolean;
  allowGet: boolean;
};

export type ExpressInvalidRoutesOptions = {
  apis: ExpressApi[];
  allowPost: boolean;
  allowOptions: boolean;
  allowGet: boolean;
};

export type ExpressRateLimiterOptions = {
  config: BackendUtilsConfig;
};

export type ExpressServiceOptions = {
  config: BackendUtilsConfig | BackendUtilsConfigBasic;
  serviceName: BackendServiceName;
  apis: ExpressApi[];
  allowPost: boolean;
  allowOptions: boolean;
  allowGet: boolean;
  payloadLimit: string | undefined; // eg: 2mb
};

export type ExpressService = {
  expressApp: express.Express;
  httpServer: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
  start(apis: ExpressApi[]): void;
};

packages/cwc-backend-utils/src/express/cors.ts

2 versions

Version 1

'use strict';
import { NextFunction, Request, Response } from 'express';
import { ExpressCorsOptions } from '../backendUtils.types';

// Enable CORS for all methods
// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin

export const cors = ({ config, allowGet, allowOptions, allowPost }: ExpressCorsOptions) => {
  return (req: Request, res: Response, next: NextFunction) => {
    // *****************************************************************************************
    // having cors problems?
    // 1. nginx server.conf - make sure you have updated the nginx server.conf file and DEPLOYED it to the server
    // 2. have you added the api in ./src/index.ts ?
    //   const apis: AuthApi[] = [new LogonApiV1()];
    // 2. is the uri/url correct? if a route can't be found it will not return OK for OPTIONS
    //   route: /auth/v1/logon
    //   request path: /auth/auth/v1/logon  <-- will fail
    // *****************************************************************************************

    if (config.isDev || config.isE2E) {
      if (req.headers.origin) {
        res.header('Access-Control-Allow-Origin', req.headers.origin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      } else {
        res.header('Access-Control-Allow-Origin', '*');
      }
    }

    if (config.isTest) {
      // Allow devCorsOrigin for localhost development against test services
      // (Browser security enforces origin headers - they cannot be forged)
      if (config.devCorsOrigin && req.headers.origin === config.devCorsOrigin) {
        res.header('Access-Control-Allow-Origin', config.devCorsOrigin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      } else {
        res.header('Access-Control-Allow-Origin', config.corsOrigin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      }
    }

    if (config.isProduction) {
      res.header('Access-Control-Allow-Origin', config.corsOrigin);
      res.header('Vary', 'Origin');
      res.header('Access-Control-Allow-Credentials', 'true');
    }

    res.header(
      'Access-Control-Allow-Headers',
      'Authorization, Origin, X-Requested-With, Content-Type, Accept'
    );

    const allowedMethods: string[] = [];
    if (allowGet) {
      allowedMethods.push('GET');
    }
    if (allowOptions) {
      allowedMethods.push('OPTIONS');
    }
    if (allowPost) {
      allowedMethods.push('POST');
    }
    res.header('Access-Control-Allow-Methods', allowedMethods.join());
    res.header('Access-Control-Expose-Headers', 'Authorization');
    next();
  };
};

Version 2 (latest)

'use strict';
import { NextFunction, Request, Response } from 'express';
import { ExpressCorsOptions } from '../backendUtils.types';

// Enable CORS for all methods
// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin

export const cors = ({ config, allowGet, allowOptions, allowPost }: ExpressCorsOptions) => {
  return (req: Request, res: Response, next: NextFunction) => {
    // *****************************************************************************************
    // having cors problems?
    // 1. nginx server.conf - make sure you have updated the nginx server.conf file and DEPLOYED it to the server
    // 2. have you added the api in ./src/index.ts ?
    //   const apis: AuthApi[] = [new LogonApiV1()];
    // 2. is the uri/url correct? if a route can't be found it will not return OK for OPTIONS
    //   route: /auth/v1/logon
    //   request path: /auth/auth/v1/logon  <-- will fail
    // *****************************************************************************************

    if (config.isDev || config.isE2E) {
      if (req.headers.origin) {
        res.header('Access-Control-Allow-Origin', req.headers.origin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      } else {
        res.header('Access-Control-Allow-Origin', '*');
      }
    }

    if (config.isTest) {
      // Allow devCorsOrigin for localhost development against test services
      // (Browser security enforces origin headers - they cannot be forged)
      if (config.devCorsOrigin && req.headers.origin === config.devCorsOrigin) {
        res.header('Access-Control-Allow-Origin', config.devCorsOrigin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      } else {
        res.header('Access-Control-Allow-Origin', config.corsOrigin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      }
    }

    if (config.isProd) {
      res.header('Access-Control-Allow-Origin', config.corsOrigin);
      res.header('Vary', 'Origin');
      res.header('Access-Control-Allow-Credentials', 'true');
    }

    res.header(
      'Access-Control-Allow-Headers',
      'Authorization, Origin, X-Requested-With, Content-Type, Accept'
    );

    const allowedMethods: string[] = [];
    if (allowGet) {
      allowedMethods.push('GET');
    }
    if (allowOptions) {
      allowedMethods.push('OPTIONS');
    }
    if (allowPost) {
      allowedMethods.push('POST');
    }
    res.header('Access-Control-Allow-Methods', allowedMethods.join());
    res.header('Access-Control-Expose-Headers', 'Authorization');
    next();
  };
};

packages/cwc-backend-utils/src/index.ts

export * from './SqlClient';
export * from './AuthClient';
export * from './Logger';
export * from './SqlClientKeysUtil';
export * from './backendUtils.types';
export * from './express';
export * from './loadDotEnv';
export * from './localSecretsPaths';
export * from './configHelpers';

packages/cwc-backend-utils/src/loadDotEnv.ts

3 versions

Version 1

import * as dotenv from 'dotenv';
import { RuntimeEnvironment } from 'cwc-types';
import { resolve } from 'path';
import { BackendServiceName } from './backendUtils.types';
import { getSecretsEnvFilePath } from './localSecretsPaths';

export type LoadDotEnvOptions = {
  serviceName: BackendServiceName;
  environment: RuntimeEnvironment;
  debug?: boolean;
};

export const loadDotEnv = ({
  serviceName,
  environment,
  debug = false,
}: LoadDotEnvOptions): void => {
  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, { environment });
  }

  const runningOnServer = environment === 'test' || environment === 'prod';
  const runningLocally = !runningOnServer;

  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, { runningOnServer, runningLocally });
  }

  // Construct path relative to process.cwd() (typically package directory when running dev script)
  // Directory structure: coding-with-claude/source/coding-with-claude-application/packages/{service}
  // Local development: ../../../../private/cwc-secrets/env/{environment}.{serviceName}.env
  // Server deployment: .env.{environment}
  const envPath = runningLocally
    ? resolve(process.cwd(), `../../../../private/cwc-secrets/env/${environment}.${serviceName}.env`)
    : resolve(process.cwd(), `.env.${environment}`);

  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, { envPath, cwd: process.cwd() });
  }

  dotenv.config({ path: envPath });
  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, {
      process_env_ENVIRONMENT: process.env['ENVIRONMENT'],
    });
  }
};

Version 2

import * as dotenv from 'dotenv';
import { RuntimeEnvironment } from 'cwc-types';
import { resolve } from 'path';
import { BackendServiceName } from './backendUtils.types';
import { getSecretsEnvFilePath } from './localSecretsPaths';

export type LoadDotEnvOptions = {
  serviceName: BackendServiceName;
  environment: RuntimeEnvironment;
  debug?: boolean;
};

export const loadDotEnv = ({
  serviceName,
  environment,
  debug = false,
}: LoadDotEnvOptions): void => {
  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, { environment });
  }

  const runningOnServer = environment === 'test' || environment === 'prod';
  const runningLocally = !runningOnServer;

  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, { runningOnServer, runningLocally });
  }

  // Local development: uses getSecretsEnvFilePath() for absolute path to ~/coding-with-claude/private/cwc-secrets/env/
  // Server deployment: .env.{environment} relative to process.cwd()
  const envPath = runningLocally
    ? getSecretsEnvFilePath(environment, serviceName)
    : resolve(process.cwd(), `.env.${environment}`);

  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, { envPath, cwd: process.cwd() });
  }

  dotenv.config({ path: envPath });
  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, {
      process_env_ENVIRONMENT: process.env['ENVIRONMENT'],
    });
  }
};

Version 3 (latest)

import * as dotenv from 'dotenv';
import { RuntimeEnvironment } from 'cwc-types';
import { BackendServiceName } from './backendUtils.types';
import { getSecretsEnvFilePath } from './localSecretsPaths';

export type LoadDotEnvOptions = {
  serviceName: BackendServiceName;
  environment: RuntimeEnvironment;
  debug?: boolean;
};

export const loadDotEnv = ({
  serviceName,
  environment,
  debug = false,
}: LoadDotEnvOptions): void => {
  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, { environment });
  }

  const runningOnServer = environment === 'test' || environment === 'prod';
  const runningLocally = !runningOnServer;

  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, { runningOnServer, runningLocally });
  }

  const envPath = getSecretsEnvFilePath(runningLocally, environment, serviceName);

  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, { envPath, cwd: process.cwd() });
  }

  dotenv.config({ path: envPath });
  if (debug) {
    console.log(`loadDotEnv: ${serviceName}`, {
      process_env_ENVIRONMENT: process.env['ENVIRONMENT'],
    });
  }
};

packages/cwc-backend-utils/src/localPaths.ts.tmp

'use strict';

/**
 * Local development secrets path functions
 *
 * Path Resolution:
 * - Local (dev/unit/e2e): Uses absolute paths via os.homedir() → ~/coding-with-claude/private/cwc-secrets
 * - Server (test/prod): Uses relative paths from deployment directory
 *
 * Functions that take `runningLocally` parameter encapsulate both local and server path logic.
 * Functions without the parameter are for local-only paths (like getSecretsPath, getSecretsEnvPath).
 */

import os from 'node:os';
import path from 'node:path';
import type { RuntimeEnvironment } from 'cwc-types';
import type { BackendServiceName } from './backendUtils.types';

/**
 * Base path to the cwc-secrets directory for local development
 * @returns ~/coding-with-claude/private/cwc-secrets
 */
export function getSecretsPath(): string {
  return path.join(os.homedir(), 'coding-with-claude/private/cwc-secrets');
}

/**
 * Path to the environment files directory (local only)
 * @returns ~/coding-with-claude/private/cwc-secrets/env
 */
export function getSecretsEnvPath(): string {
  return path.join(getSecretsPath(), 'env');
}

/**
 * Path to the SQL client API keys directory
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys
 *          Server: ./sql-client-api-keys
 */
export function getSecretsSqlClientApiKeysPath(runningLocally: boolean): string {
  return runningLocally
    ? path.join(getSecretsPath(), 'sql-client-api-keys')
    : './sql-client-api-keys';
}

/**
 * Path to the configuration helper directory
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/configuration-helper
 *          Server: ./configuration-helper
 */
export function getSecretsConfigHelperPath(runningLocally: boolean): string {
  return runningLocally
    ? path.join(getSecretsPath(), 'configuration-helper')
    : './configuration-helper';
}

/**
 * Path to the deployment configuration directory
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/deployment
 *          Server: ./deployment
 */
export function getSecretsDeploymentPath(runningLocally: boolean): string {
  return runningLocally
    ? path.join(getSecretsPath(), 'deployment')
    : './deployment';
}

/**
 * Constructs the full path to an environment file
 *
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @param environment - The runtime environment
 * @param serviceName - The backend service name
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/env/{environment}.{serviceName}.env
 *          Server: .env.{environment}
 *
 * @example
 * getSecretsEnvFilePath(true, 'dev', 'cwc-api')
 * // Returns: /Users/.../coding-with-claude/private/cwc-secrets/env/dev.cwc-api.env
 *
 * getSecretsEnvFilePath(false, 'prod', 'cwc-api')
 * // Returns: .env.prod
 */
export function getSecretsEnvFilePath(
  runningLocally: boolean,
  environment: RuntimeEnvironment,
  serviceName: BackendServiceName
): string {
  return runningLocally
    ? path.join(getSecretsEnvPath(), `${environment}.${serviceName}.env`)
    : `.env.${environment}`;
}

packages/cwc-backend-utils/src/localSecretsPaths.ts

3 versions

Version 1

'use strict';

/**
 * Local development secrets path functions
 *
 * IMPORTANT: These paths are ONLY used when running locally (dev/unit/e2e environments).
 * Server deployments (test/prod) use paths relative to the deployment directory.
 *
 * Directory structure:
 * ~/coding-with-claude/private/cwc-secrets/
 *   ├── env/                          # Environment files
 *   │   ├── dev.cwc-api.env
 *   │   ├── dev.cwc-auth.env
 *   │   ├── unit.cwc-api.env
 *   │   └── ...
 *   ├── sql-client-api-keys/          # SQL client JWT keys
 *   │   ├── sql-client-api-key-private.pem
 *   │   └── sql-client-api-key-public.pem
 *   ├── configuration-helper/         # Deployment secrets (JSON)
 *   └── deployment/                   # Deployment configs
 *       ├── servers.json
 *       └── ssh-keys/
 */

import os from 'node:os';
import path from 'node:path';
import type { RuntimeEnvironment } from 'cwc-types';
import type { BackendServiceName } from './backendUtils.types';

/**
 * Base path to the cwc-secrets directory for local development
 * @returns ~/coding-with-claude/private/cwc-secrets
 */
export function getSecretsPath(): string {
  return path.join(os.homedir(), 'coding-with-claude/private/cwc-secrets');
}

/**
 * Path to the environment files directory
 * @returns ~/coding-with-claude/private/cwc-secrets/env
 */
export function getSecretsEnvPath(): string {
  return path.join(getSecretsPath(), 'env');
}

/**
 * Path to the SQL client API keys directory
 * @returns ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys
 */
export function getSecretsSqlClientApiKeysPath(): string {
  return path.join(getSecretsPath(), 'sql-client-api-keys');
}

/**
 * Path to the configuration helper directory
 * @returns ~/coding-with-claude/private/cwc-secrets/configuration-helper
 */
export function getSecretsConfigHelperPath(): string {
  return path.join(getSecretsPath(), 'configuration-helper');
}

/**
 * Path to the deployment configuration directory
 * @returns ~/coding-with-claude/private/cwc-secrets/deployment
 */
export function getSecretsDeploymentPath(): string {
  return path.join(getSecretsPath(), 'deployment');
}

/**
 * Constructs the full path to an environment file for local development
 *
 * @param environment - The runtime environment (dev, unit, e2e)
 * @param serviceName - The backend service name
 * @returns Full absolute path to the .env file
 *
 * @example
 * getSecretsEnvFilePath('dev', 'cwc-api')
 * // Returns: /Users/.../coding-with-claude/private/cwc-secrets/env/dev.cwc-api.env
 */
export function getSecretsEnvFilePath(
  environment: RuntimeEnvironment,
  serviceName: BackendServiceName
): string {
  return path.join(getSecretsEnvPath(), `${environment}.${serviceName}.env`);
}

Version 2

'use strict';

/**
 * Secrets path functions for local and server environments
 *
 * IMPORTANT: These functions handle both local (dev/unit/e2e) and server (test/prod) paths.
 * Pass `runningLocally` to get the appropriate path for the environment.
 *
 * Directory structure (local):
 * ~/coding-with-claude/private/cwc-secrets/
 *   ├── env/                          # Environment files
 *   │   ├── dev.cwc-api.env
 *   │   ├── dev.cwc-auth.env
 *   │   ├── unit.cwc-api.env
 *   │   └── ...
 *   ├── sql-client-api-keys/          # SQL client JWT keys
 *   │   ├── sql-client-api-key-private.pem
 *   │   └── sql-client-api-key-public.pem
 *   ├── configuration-helper/         # Deployment secrets (JSON)
 *   └── deployment/                   # Deployment configs
 *       ├── servers.json
 *       └── ssh-keys/
 */

import os from 'node:os';
import path from 'node:path';
import type { RuntimeEnvironment } from 'cwc-types';
import type { BackendServiceName } from './backendUtils.types';

/**
 * Base path to the cwc-secrets directory for local development
 * @returns ~/coding-with-claude/private/cwc-secrets
 */
export function getSecretsPath(): string {
  return path.join(os.homedir(), 'coding-with-claude/private/cwc-secrets');
}

/**
 * Path to the environment files directory (local only)
 * @returns ~/coding-with-claude/private/cwc-secrets/env
 */
export function getSecretsEnvPath(): string {
  return path.join(getSecretsPath(), 'env');
}

/**
 * Path to the SQL client API keys directory
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys
 *          Server: ./sql-client-api-keys
 */
export function getSecretsSqlClientApiKeysPath(runningLocally: boolean): string {
  return runningLocally
    ? path.join(getSecretsPath(), 'sql-client-api-keys')
    : './sql-client-api-keys';
}

/**
 * Path to the configuration helper directory
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/configuration-helper
 *          Server: ./configuration-helper
 */
export function getSecretsConfigHelperPath(runningLocally: boolean): string {
  return runningLocally
    ? path.join(getSecretsPath(), 'configuration-helper')
    : './configuration-helper';
}

/**
 * Path to the deployment configuration directory
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/deployment
 *          Server: ./deployment
 */
export function getSecretsDeploymentPath(runningLocally: boolean): string {
  return runningLocally
    ? path.join(getSecretsPath(), 'deployment')
    : './deployment';
}

/**
 * Constructs the full path to an environment file for local development
 *
 * Note: Server deployments use a different pattern (.env.{environment})
 * so this function is only for local environments.
 *
 * @param environment - The runtime environment (dev, unit, e2e)
 * @param serviceName - The backend service name
 * @returns Full absolute path to the .env file
 *
 * @example
 * getSecretsEnvFilePath('dev', 'cwc-api')
 * // Returns: /Users/.../coding-with-claude/private/cwc-secrets/env/dev.cwc-api.env
 */
export function getSecretsEnvFilePath(
  environment: RuntimeEnvironment,
  serviceName: BackendServiceName
): string {
  return path.join(getSecretsEnvPath(), `${environment}.${serviceName}.env`);
}

Version 3 (latest)

'use strict';

/**
 * Local development secrets path functions
 *
 * Path Resolution:
 * - Local (dev/unit/e2e): Uses absolute paths via os.homedir() → ~/coding-with-claude/private/cwc-secrets
 * - Server (test/prod): Uses relative paths from deployment directory
 *
 * Functions that take `runningLocally` parameter encapsulate both local and server path logic.
 * Functions without the parameter are for local-only paths (like getSecretsPath, getSecretsEnvPath).
 */

import os from 'node:os';
import path from 'node:path';
import type { RuntimeEnvironment } from 'cwc-types';
import type { BackendServiceName } from './backendUtils.types';

/**
 * Base path to the cwc-secrets directory for local development
 * @returns ~/coding-with-claude/private/cwc-secrets
 */
export function getSecretsPath(): string {
  return path.join(os.homedir(), 'coding-with-claude/private/cwc-secrets');
}

/**
 * Path to the environment files directory (local only)
 * @returns ~/coding-with-claude/private/cwc-secrets/env
 */
export function getSecretsEnvPath(): string {
  return path.join(getSecretsPath(), 'env');
}

/**
 * Path to the SQL client API keys directory
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/sql-client-api-keys
 *          Server: ./sql-client-api-keys
 */
export function getSecretsSqlClientApiKeysPath(runningLocally: boolean): string {
  return runningLocally
    ? path.join(getSecretsPath(), 'sql-client-api-keys')
    : './sql-client-api-keys';
}

/**
 * Path to the configuration helper directory
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/configuration-helper
 *          Server: ./configuration-helper
 */
export function getSecretsConfigHelperPath(runningLocally: boolean): string {
  return runningLocally
    ? path.join(getSecretsPath(), 'configuration-helper')
    : './configuration-helper';
}

/**
 * Path to the deployment configuration directory
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/deployment
 *          Server: ./deployment
 */
export function getSecretsDeploymentPath(runningLocally: boolean): string {
  return runningLocally
    ? path.join(getSecretsPath(), 'deployment')
    : './deployment';
}

/**
 * Constructs the full path to an environment file
 *
 * @param runningLocally - true for dev/unit/e2e, false for test/prod
 * @param environment - The runtime environment
 * @param serviceName - The backend service name
 * @returns Local: ~/coding-with-claude/private/cwc-secrets/env/{environment}.{serviceName}.env
 *          Server: .env.{environment}
 *
 * @example
 * getSecretsEnvFilePath(true, 'dev', 'cwc-api')
 * // Returns: /Users/.../coding-with-claude/private/cwc-secrets/env/dev.cwc-api.env
 *
 * getSecretsEnvFilePath(false, 'prod', 'cwc-api')
 * // Returns: .env.prod
 */
export function getSecretsEnvFilePath(
  runningLocally: boolean,
  environment: RuntimeEnvironment,
  serviceName: BackendServiceName
): string {
  return runningLocally
    ? path.join(getSecretsEnvPath(), `${environment}.${serviceName}.env`)
    : `.env.${environment}`;
}

packages/cwc-backend-utils/src/SqlClientKeysUtil.ts

3 versions

Version 1

'use strict';

import fs from 'node:fs';
import { v4 as uuidv4 } from 'uuid';
import jsonwebtoken, { SignOptions } from 'jsonwebtoken';
import { Logger } from './Logger';
import { BackendServiceName, BackendUtilsConfig } from './backendUtils.types';

const codeLocation = 'src/SqlClientKeysUtil.ts';

type SqlClientKeys = {
  privateKey: Buffer;
  publicKey: Buffer;
};

type GetApiTokenOptions = {
  userPkId: number | undefined;
};

type CreateSqlClientTokenOptions = {
  userPkId: number | undefined;
  expiresIn: string; // '30s'
};

type SqlClientKeysUtilOptions = {
  config: BackendUtilsConfig;
  enableLogging: boolean;
  clientName: BackendServiceName;
};

export class SqlClientKeysUtil {
  private config: BackendUtilsConfig;
  private enableLogging: boolean;
  private sqlClientKeys: SqlClientKeys;
  private apiToken: string | undefined;
  private clientName: BackendServiceName;

  constructor({ config, enableLogging, clientName }: SqlClientKeysUtilOptions) {
    this.config = config;
    this.enableLogging = enableLogging;
    this.clientName = clientName;
    const runningLocally = config.isDev || config.isUnit || config.isE2E;
    const keyPath = runningLocally ? `../../../cwc-secrets/sql-client-api-keys` : `./sql-client-api-keys`;
    this.sqlClientKeys = {
      privateKey: fs.readFileSync(`${keyPath}/sql-client-api-key-private.pem`),
      publicKey: fs.readFileSync(`${keyPath}/sql-client-api-key-public.pem`),
    };
  }

  public async getApiToken({ userPkId }: GetApiTokenOptions) {
    const newTokenNeeded = await this.needNewApiToken();
    if (newTokenNeeded) {
      const expiresIn = '30s'; // 30 seconds
      await this.createSqlClientToken({
        userPkId,
        expiresIn,
      });
    }
    return this.apiToken;
  }

  private async needNewApiToken() {
    if (!this.apiToken) {
      return true;
    }
    const decodedPayload = jsonwebtoken.decode(this.apiToken);

    if (!decodedPayload || typeof decodedPayload !== 'object') {
      return true;
    }
    if (!decodedPayload?.exp) {
      return true;
    }

    const exp = decodedPayload.exp;
    const curr = new Date().valueOf() / 1000;
    const remaining = exp - curr;

    if (remaining < 5) {
      return true;
    }

    return false;
  }

  private async createSqlClientToken({ userPkId, expiresIn = '30s' }: CreateSqlClientTokenOptions) {
    // payload is passed to `jsonwebtoken.sign()`
    const payload = {
      dataJwtId: uuidv4(),
      clientName: this.clientName,
    };

    type SignResultType = {
      error?: Error | null;
      encoded?: string;
    };

    const signResult: SignResultType = await new Promise((resolve) => {
      const signOptions: SignOptions = {
        // @ts-expect-error
        expiresIn,
        algorithm: 'RS256',
      };
      const signCallback = (error: Error | null, encoded: string | undefined) => {
        if (error) {
          resolve({ error });
        } else if (encoded) {
          resolve({ encoded });
        }
      };
      jsonwebtoken.sign(payload, this.sqlClientKeys.privateKey, signOptions, signCallback);
    });

    if (signResult.error && this.enableLogging) {
      const logger = new Logger({
        config: this.config,
        serviceName: this.clientName,
      });
      logger.logError({
        userPkId,
        codeLocation,
        message: 'createSqlClientToken',
        error: signResult.error,
      });
      this.apiToken = undefined;
    } else if (signResult?.encoded) {
      this.apiToken = signResult.encoded;
    } else {
      this.apiToken = undefined;
    }
  }

  public get jwtPublicKey() {
    return this.sqlClientKeys.publicKey;
  }
}

Version 2

'use strict';

import fs from 'node:fs';
import path from 'node:path';
import { v4 as uuidv4 } from 'uuid';
import jsonwebtoken, { SignOptions } from 'jsonwebtoken';
import { Logger } from './Logger';
import { BackendServiceName, BackendUtilsConfig } from './backendUtils.types';
import { getSecretsSqlClientApiKeysPath } from './localSecretsPaths';

const codeLocation = 'src/SqlClientKeysUtil.ts';

type SqlClientKeys = {
  privateKey: Buffer;
  publicKey: Buffer;
};

type GetApiTokenOptions = {
  userPkId: number | undefined;
};

type CreateSqlClientTokenOptions = {
  userPkId: number | undefined;
  expiresIn: string; // '30s'
};

type SqlClientKeysUtilOptions = {
  config: BackendUtilsConfig;
  enableLogging: boolean;
  clientName: BackendServiceName;
};

export class SqlClientKeysUtil {
  private config: BackendUtilsConfig;
  private enableLogging: boolean;
  private sqlClientKeys: SqlClientKeys;
  private apiToken: string | undefined;
  private clientName: BackendServiceName;

  constructor({ config, enableLogging, clientName }: SqlClientKeysUtilOptions) {
    this.config = config;
    this.enableLogging = enableLogging;
    this.clientName = clientName;
    const runningLocally = config.isDev || config.isUnit || config.isE2E;
    const keyPath = runningLocally ? getSecretsSqlClientApiKeysPath() : './sql-client-api-keys';
    this.sqlClientKeys = {
      privateKey: fs.readFileSync(path.join(keyPath, 'sql-client-api-key-private.pem')),
      publicKey: fs.readFileSync(path.join(keyPath, 'sql-client-api-key-public.pem')),
    };
  }

  public async getApiToken({ userPkId }: GetApiTokenOptions) {
    const newTokenNeeded = await this.needNewApiToken();
    if (newTokenNeeded) {
      const expiresIn = '30s'; // 30 seconds
      await this.createSqlClientToken({
        userPkId,
        expiresIn,
      });
    }
    return this.apiToken;
  }

  private async needNewApiToken() {
    if (!this.apiToken) {
      return true;
    }
    const decodedPayload = jsonwebtoken.decode(this.apiToken);

    if (!decodedPayload || typeof decodedPayload !== 'object') {
      return true;
    }
    if (!decodedPayload?.exp) {
      return true;
    }

    const exp = decodedPayload.exp;
    const curr = new Date().valueOf() / 1000;
    const remaining = exp - curr;

    if (remaining < 5) {
      return true;
    }

    return false;
  }

  private async createSqlClientToken({ userPkId, expiresIn = '30s' }: CreateSqlClientTokenOptions) {
    // payload is passed to `jsonwebtoken.sign()`
    const payload = {
      dataJwtId: uuidv4(),
      clientName: this.clientName,
    };

    type SignResultType = {
      error?: Error | null;
      encoded?: string;
    };

    const signResult: SignResultType = await new Promise((resolve) => {
      const signOptions: SignOptions = {
        // @ts-expect-error
        expiresIn,
        algorithm: 'RS256',
      };
      const signCallback = (error: Error | null, encoded: string | undefined) => {
        if (error) {
          resolve({ error });
        } else if (encoded) {
          resolve({ encoded });
        }
      };
      jsonwebtoken.sign(payload, this.sqlClientKeys.privateKey, signOptions, signCallback);
    });

    if (signResult.error && this.enableLogging) {
      const logger = new Logger({
        config: this.config,
        serviceName: this.clientName,
      });
      logger.logError({
        userPkId,
        codeLocation,
        message: 'createSqlClientToken',
        error: signResult.error,
      });
      this.apiToken = undefined;
    } else if (signResult?.encoded) {
      this.apiToken = signResult.encoded;
    } else {
      this.apiToken = undefined;
    }
  }

  public get jwtPublicKey() {
    return this.sqlClientKeys.publicKey;
  }
}

Version 3 (latest)

'use strict';

import fs from 'node:fs';
import path from 'node:path';
import { v4 as uuidv4 } from 'uuid';
import jsonwebtoken, { SignOptions } from 'jsonwebtoken';
import { Logger } from './Logger';
import { BackendServiceName, BackendUtilsConfig } from './backendUtils.types';
import { getSecretsSqlClientApiKeysPath } from './localSecretsPaths';

const codeLocation = 'src/SqlClientKeysUtil.ts';

type SqlClientKeys = {
  privateKey: Buffer;
  publicKey: Buffer;
};

type GetApiTokenOptions = {
  userPkId: number | undefined;
};

type CreateSqlClientTokenOptions = {
  userPkId: number | undefined;
  expiresIn: string; // '30s'
};

type SqlClientKeysUtilOptions = {
  config: BackendUtilsConfig;
  enableLogging: boolean;
  clientName: BackendServiceName;
};

export class SqlClientKeysUtil {
  private config: BackendUtilsConfig;
  private enableLogging: boolean;
  private sqlClientKeys: SqlClientKeys;
  private apiToken: string | undefined;
  private clientName: BackendServiceName;

  constructor({ config, enableLogging, clientName }: SqlClientKeysUtilOptions) {
    this.config = config;
    this.enableLogging = enableLogging;
    this.clientName = clientName;
    const runningLocally = config.isDev || config.isUnit || config.isE2E;
    const keyPath = getSecretsSqlClientApiKeysPath(runningLocally);
    this.sqlClientKeys = {
      privateKey: fs.readFileSync(path.join(keyPath, 'sql-client-api-key-private.pem')),
      publicKey: fs.readFileSync(path.join(keyPath, 'sql-client-api-key-public.pem')),
    };
  }

  public async getApiToken({ userPkId }: GetApiTokenOptions) {
    const newTokenNeeded = await this.needNewApiToken();
    if (newTokenNeeded) {
      const expiresIn = '30s'; // 30 seconds
      await this.createSqlClientToken({
        userPkId,
        expiresIn,
      });
    }
    return this.apiToken;
  }

  private async needNewApiToken() {
    if (!this.apiToken) {
      return true;
    }
    const decodedPayload = jsonwebtoken.decode(this.apiToken);

    if (!decodedPayload || typeof decodedPayload !== 'object') {
      return true;
    }
    if (!decodedPayload?.exp) {
      return true;
    }

    const exp = decodedPayload.exp;
    const curr = new Date().valueOf() / 1000;
    const remaining = exp - curr;

    if (remaining < 5) {
      return true;
    }

    return false;
  }

  private async createSqlClientToken({ userPkId, expiresIn = '30s' }: CreateSqlClientTokenOptions) {
    // payload is passed to `jsonwebtoken.sign()`
    const payload = {
      dataJwtId: uuidv4(),
      clientName: this.clientName,
    };

    type SignResultType = {
      error?: Error | null;
      encoded?: string;
    };

    const signResult: SignResultType = await new Promise((resolve) => {
      const signOptions: SignOptions = {
        // @ts-expect-error
        expiresIn,
        algorithm: 'RS256',
      };
      const signCallback = (error: Error | null, encoded: string | undefined) => {
        if (error) {
          resolve({ error });
        } else if (encoded) {
          resolve({ encoded });
        }
      };
      jsonwebtoken.sign(payload, this.sqlClientKeys.privateKey, signOptions, signCallback);
    });

    if (signResult.error && this.enableLogging) {
      const logger = new Logger({
        config: this.config,
        serviceName: this.clientName,
      });
      logger.logError({
        userPkId,
        codeLocation,
        message: 'createSqlClientToken',
        error: signResult.error,
      });
      this.apiToken = undefined;
    } else if (signResult?.encoded) {
      this.apiToken = signResult.encoded;
    } else {
      this.apiToken = undefined;
    }
  }

  public get jwtPublicKey() {
    return this.sqlClientKeys.publicKey;
  }
}

packages/cwc-configuration-helper/CLAUDE.md

2 versions

Version 1

cwc-configuration-helper Package

CLI tool that generates, validates, and diffs .env files by dynamically parsing TypeScript config types from backend packages.

Core Design Principle

Zero maintenance through AST parsing: This tool reads config.types.ts files directly using the TypeScript Compiler API. When config types change in any package, the helper automatically reflects those changes without needing to update the tool itself.

How It Works

Package Discovery: Scans packages/cwc-*/src/config/config.types.ts for backend packages with configuration
AST Parsing: Uses TypeScript Compiler API to extract type definitions, property names, and types
Name Conversion: Converts camelCase properties to SCREAMING_SNAKE_CASE env vars
Generation: Creates .env files with proper structure, comments, and placeholders

Config Type Pattern (Required)

For a package to be discovered and parsed, it must follow this exact pattern:

// packages/cwc-{name}/src/config/config.types.ts

export type Cwc{Name}ConfigSecrets = {
  databasePassword: string;
  apiKey: string;
};

export type Cwc{Name}Config = {
  // Environment (derived - skipped in .env)
  runtimeEnvironment: RuntimeEnvironment;
  isProd: boolean;
  isDev: boolean;
  isTest: boolean;
  isUnit: boolean;
  isE2E: boolean;

  // Regular properties
  servicePort: number;
  corsOrigin: string;
  debugMode: boolean;

  // Secrets nested under 'secrets' property
  secrets: Cwc{Name}ConfigSecrets;
};

Naming conventions:

Main config type: Cwc{PascalCaseName}Config
Secrets type: Cwc{PascalCaseName}ConfigSecrets
Secrets must be nested under a secrets property

Secrets File Structure

Flat key-value structure - no package namespacing required:

{
  "DATABASE_PASSWORD": "secretpassword",
  "USER_JWT_SECRET": "secret-key-here",
  "SQL_CLIENT_API_KEY": "-----BEGIN PUBLIC KEY-----\n..."
}

The tool automatically matches env var names from each package's ConfigSecrets type against this flat list. Shared secrets (like DATABASE_PASSWORD) are automatically used by all packages that need them.

Name Conversion Rules

camelCase properties → SCREAMING_SNAKE_CASE:

Property Name	Environment Variable
`servicePort`	`SERVICE_PORT`
`corsOrigin`	`CORS_ORIGIN`
`rateLimiterPoints`	`RATE_LIMITER_POINTS`
`userJwtSecret`	`USER_JWT_SECRET`
`dataUri`	`DATA_URI`

Properties Automatically Skipped

These derived/computed properties are excluded from .env generation:

isProduction, isDevelopment, isTest, isUnitTest, isEndToEnd
secrets (handled separately via the secrets type)

Centralized Configuration (configuration.ts)

The configuration.ts file provides centralized config values that are automatically used during .env generation:

RuntimeConfigValues: Environment-specific values (corsOrigin, dataUri, smtp settings, database settings, etc.)
ServiceConfigValues: Service-specific overrides (port, rateLimiter)

Dynamic Property Lookup: The getValueFromCentralConfig function uses dynamic lookup (propName in configRecord) rather than hardcoded mappings. When adding new properties to RuntimeConfigValues, they are automatically available without modifying envGenerator.ts.

Special Mappings:

servicePort → config.port (renamed property)
rateLimiterPoints/Duration → config.rateLimiter.points/duration (nested object)
smtp* properties → flattened from config.smtp object

Value Handling

Undefined vs Missing:

Property exists in config with undefined value → empty string in .env (intentionally not set)
Property not found in config → placeholder like <VALUE> (needs configuration)

Multiline Secrets: Values containing newlines (like PEM keys) are automatically:

Escaped: \n replaced with \\n
Quoted: wrapped in double quotes

Example: SQL_CLIENT_API_KEY="-----BEGIN PUBLIC KEY-----\n..."

Error Messages

Missing values are categorized by type with appropriate guidance:

Missing secrets → "update secrets file: {path}"
Missing config values → "update configuration.ts"

Architecture

src/
├── index.ts              # CLI entry point (Commander.js)
├── types.ts              # Type definitions
├── configuration.ts      # Centralized runtime and service config values
├── nameConverter.ts      # camelCase <-> SCREAMING_SNAKE_CASE
├── packageDiscovery.ts   # Discovers packages with config.types.ts
├── typeParser.ts         # TypeScript AST parsing
├── envGenerator.ts       # .env file generation
└── commands/
    ├── generate.ts       # Generate command
    ├── validate.ts       # Validate command
    ├── diff.ts           # Diff command
    └── index.ts          # Command exports

Version 2 (latest)

cwc-configuration-helper Package

CLI tool that generates, validates, and diffs .env files by dynamically parsing TypeScript config types from backend packages.

Core Design Principle

How It Works

Package Discovery: Scans packages/cwc-*/src/config/config.types.ts for backend packages with configuration
AST Parsing: Uses TypeScript Compiler API to extract type definitions, property names, and types
Name Conversion: Converts camelCase properties to SCREAMING_SNAKE_CASE env vars
Generation: Creates .env files with proper structure, comments, and placeholders

Config Type Pattern (Required)

For a package to be discovered and parsed, it must follow this exact pattern:

// packages/cwc-{name}/src/config/config.types.ts

export type Cwc{Name}ConfigSecrets = {
  databasePassword: string;
  apiKey: string;
};

export type Cwc{Name}Config = {
  // Environment (derived - skipped in .env)
  runtimeEnvironment: RuntimeEnvironment;
  isProd: boolean;
  isDev: boolean;
  isTest: boolean;
  isUnit: boolean;
  isE2E: boolean;

  // Regular properties
  servicePort: number;
  corsOrigin: string;
  debugMode: boolean;

  // Secrets nested under 'secrets' property
  secrets: Cwc{Name}ConfigSecrets;
};

Naming conventions:

Main config type: Cwc{PascalCaseName}Config
Secrets type: Cwc{PascalCaseName}ConfigSecrets
Secrets must be nested under a secrets property

Secrets File Structure

Flat key-value structure - no package namespacing required:

{
  "DATABASE_PASSWORD": "secretpassword",
  "USER_JWT_SECRET": "secret-key-here",
  "SQL_CLIENT_API_KEY": "-----BEGIN PUBLIC KEY-----\n..."
}

Name Conversion Rules

camelCase properties → SCREAMING_SNAKE_CASE:

Property Name	Environment Variable
`servicePort`	`SERVICE_PORT`
`corsOrigin`	`CORS_ORIGIN`
`rateLimiterPoints`	`RATE_LIMITER_POINTS`
`userJwtSecret`	`USER_JWT_SECRET`
`dataUri`	`DATA_URI`

Properties Automatically Skipped

These derived/computed properties are excluded from .env generation:

isProd, isDev, isTest, isUnit, isE2E
secrets (handled separately via the secrets type)

Centralized Configuration (configuration.ts)

The configuration.ts file provides centralized config values that are automatically used during .env generation:

RuntimeConfigValues: Environment-specific values (corsOrigin, dataUri, smtp settings, database settings, etc.)
ServiceConfigValues: Service-specific overrides (port, rateLimiter)

Special Mappings:

servicePort → config.port (renamed property)
rateLimiterPoints/Duration → config.rateLimiter.points/duration (nested object)
smtp* properties → flattened from config.smtp object

Value Handling

Undefined vs Missing:

Property exists in config with undefined value → empty string in .env (intentionally not set)
Property not found in config → placeholder like <VALUE> (needs configuration)

Multiline Secrets: Values containing newlines (like PEM keys) are automatically:

Escaped: \n replaced with \\n
Quoted: wrapped in double quotes

Example: SQL_CLIENT_API_KEY="-----BEGIN PUBLIC KEY-----\n..."

Error Messages

Missing values are categorized by type with appropriate guidance:

Missing secrets → "update secrets file: {path}"
Missing config values → "update configuration.ts"

Architecture

src/
├── index.ts              # CLI entry point (Commander.js)
├── types.ts              # Type definitions
├── configuration.ts      # Centralized runtime and service config values
├── nameConverter.ts      # camelCase <-> SCREAMING_SNAKE_CASE
├── packageDiscovery.ts   # Discovers packages with config.types.ts
├── typeParser.ts         # TypeScript AST parsing
├── envGenerator.ts       # .env file generation
└── commands/
    ├── generate.ts       # Generate command
    ├── validate.ts       # Validate command
    ├── diff.ts           # Diff command
    └── index.ts          # Command exports

packages/cwc-configuration-helper/src/nameConverter.ts

2 versions

Version 1

/**
 * Name conversion utilities for transforming between camelCase and SCREAMING_SNAKE_CASE
 */

/**
 * Converts camelCase to SCREAMING_SNAKE_CASE
 *
 * Examples:
 * - servicePort -> SERVICE_PORT
 * - corsOrigin -> CORS_ORIGIN
 * - rateLimiterPoints -> RATE_LIMITER_POINTS
 * - userJwtSecret -> USER_JWT_SECRET
 * - isProd -> IS_PROD
 * - dataUri -> DATA_URI
 * - debugMode -> DEBUG_MODE
 *
 * @param camelCase The camelCase property name
 * @returns The SCREAMING_SNAKE_CASE environment variable name
 */
export function camelToScreamingSnake(camelCase: string): string {
  // Handle empty string
  if (!camelCase) {
    return '';
  }

  // Insert underscore before each uppercase letter (except at start)
  // Then convert entire string to uppercase
  return camelCase
    .replace(/([A-Z])/g, '_$1')
    .toUpperCase()
    // Remove leading underscore if property started with uppercase
    .replace(/^_/, '');
}

/**
 * Converts SCREAMING_SNAKE_CASE to camelCase
 *
 * Examples:
 * - SERVICE_PORT -> servicePort
 * - CORS_ORIGIN -> corsOrigin
 * - RATE_LIMITER_POINTS -> rateLimiterPoints
 * - USER_JWT_SECRET -> userJwtSecret
 * - IS_PRODUCTION -> isProduction
 *
 * @param screamingSnake The SCREAMING_SNAKE_CASE environment variable name
 * @returns The camelCase property name
 */
export function screamingSnakeToCamel(screamingSnake: string): string {
  // Handle empty string
  if (!screamingSnake) {
    return '';
  }

  return screamingSnake
    .toLowerCase()
    .replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
}

/**
 * Validates that a string is valid SCREAMING_SNAKE_CASE
 *
 * @param str The string to validate
 * @returns true if valid SCREAMING_SNAKE_CASE
 */
export function isValidScreamingSnake(str: string): boolean {
  if (!str) {
    return false;
  }
  // Must be uppercase letters, digits, and underscores only
  // Cannot start with digit or underscore
  // Cannot have consecutive underscores
  return /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/.test(str);
}

/**
 * Validates that a string is valid camelCase
 *
 * @param str The string to validate
 * @returns true if valid camelCase
 */
export function isValidCamelCase(str: string): boolean {
  if (!str) {
    return false;
  }
  // Must start with lowercase letter
  // Can contain letters and digits
  return /^[a-z][a-zA-Z0-9]*$/.test(str);
}

Version 2 (latest)

/**
 * Name conversion utilities for transforming between camelCase and SCREAMING_SNAKE_CASE
 */

/**
 * Converts camelCase to SCREAMING_SNAKE_CASE
 *
 * Examples:
 * - servicePort -> SERVICE_PORT
 * - corsOrigin -> CORS_ORIGIN
 * - rateLimiterPoints -> RATE_LIMITER_POINTS
 * - userJwtSecret -> USER_JWT_SECRET
 * - isProd -> IS_PROD
 * - dataUri -> DATA_URI
 * - debugMode -> DEBUG_MODE
 *
 * @param camelCase The camelCase property name
 * @returns The SCREAMING_SNAKE_CASE environment variable name
 */
export function camelToScreamingSnake(camelCase: string): string {
  // Handle empty string
  if (!camelCase) {
    return '';
  }

  // Insert underscore before each uppercase letter (except at start)
  // Then convert entire string to uppercase
  return camelCase
    .replace(/([A-Z])/g, '_$1')
    .toUpperCase()
    // Remove leading underscore if property started with uppercase
    .replace(/^_/, '');
}

/**
 * Converts SCREAMING_SNAKE_CASE to camelCase
 *
 * Examples:
 * - SERVICE_PORT -> servicePort
 * - CORS_ORIGIN -> corsOrigin
 * - RATE_LIMITER_POINTS -> rateLimiterPoints
 * - USER_JWT_SECRET -> userJwtSecret
 * - IS_PROD -> isProd
 *
 * @param screamingSnake The SCREAMING_SNAKE_CASE environment variable name
 * @returns The camelCase property name
 */
export function screamingSnakeToCamel(screamingSnake: string): string {
  // Handle empty string
  if (!screamingSnake) {
    return '';
  }

  return screamingSnake
    .toLowerCase()
    .replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
}

/**
 * Validates that a string is valid SCREAMING_SNAKE_CASE
 *
 * @param str The string to validate
 * @returns true if valid SCREAMING_SNAKE_CASE
 */
export function isValidScreamingSnake(str: string): boolean {
  if (!str) {
    return false;
  }
  // Must be uppercase letters, digits, and underscores only
  // Cannot start with digit or underscore
  // Cannot have consecutive underscores
  return /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/.test(str);
}

/**
 * Validates that a string is valid camelCase
 *
 * @param str The string to validate
 * @returns true if valid camelCase
 */
export function isValidCamelCase(str: string): boolean {
  if (!str) {
    return false;
  }
  // Must start with lowercase letter
  // Can contain letters and digits
  return /^[a-z][a-zA-Z0-9]*$/.test(str);
}

packages/cwc-configuration-helper/src/typeParser.ts

2 versions

Version 1

/**
 * TypeScript AST parser for extracting configuration types from config.types.ts files
 *
 * Uses the TypeScript Compiler API to parse type definitions and extract:
 * - Property names and types
 * - Optional vs required properties
 * - Nested secrets types
 * - JSDoc comments
 */

import ts from 'typescript';
import fs from 'fs';
import type { ConfigProperty, PackageConfig } from './types.js';
import { camelToScreamingSnake } from './nameConverter.js';
import type { DiscoveredPackage } from './packageDiscovery.js';

/**
 * Parses a config.types.ts file and extracts configuration schema
 *
 * @param discoveredPackage The discovered package to parse
 * @returns Parsed package configuration
 */
export function parseConfigTypes(discoveredPackage: DiscoveredPackage): PackageConfig {
  const { name: packageName, configTypesPath } = discoveredPackage;

  // Read the file
  const fileContent = fs.readFileSync(configTypesPath, 'utf-8');

  // Create a source file from the content
  const sourceFile = ts.createSourceFile(
    configTypesPath,
    fileContent,
    ts.ScriptTarget.Latest,
    true,
    ts.ScriptKind.TS
  );

  // Find the main config type and secrets type
  const configTypeName = findMainConfigType(sourceFile, packageName);
  const secretsTypeName = findSecretsType(sourceFile, packageName);

  if (!configTypeName) {
    throw new Error(
      `Could not find main config type in ${configTypesPath}. ` +
        `Expected a type like 'Cwc${pascalCase(packageName.replace('cwc-', ''))}Config'`
    );
  }

  // Extract properties from main config type
  const mainTypeNode = findTypeNode(sourceFile, configTypeName);
  if (!mainTypeNode) {
    throw new Error(`Could not find type definition for ${configTypeName}`);
  }

  // Extract properties from secrets type if exists
  let secretsTypeNode: ts.TypeAliasDeclaration | undefined;
  if (secretsTypeName) {
    secretsTypeNode = findTypeNode(sourceFile, secretsTypeName);
  }

  // Parse properties
  const { properties, secrets } = extractProperties(
    mainTypeNode,
    secretsTypeNode,
    sourceFile
  );

  return {
    packageName,
    configTypesPath,
    configTypeName,
    secretsTypeName,
    properties,
    secrets,
  };
}

/**
 * Finds the main config type name in the source file
 * Looks for patterns like CwcSqlConfig, CwcAuthConfig, CwcStorageConfig
 */
function findMainConfigType(sourceFile: ts.SourceFile, packageName: string): string | undefined {
  // Build expected type name from package name
  // cwc-sql -> CwcSqlConfig
  // cwc-auth -> CwcAuthConfig
  // cwc-backend-utils -> CwcBackendUtilsConfig
  const baseName = packageName.replace('cwc-', '');
  const expectedName = `Cwc${pascalCase(baseName)}Config`;

  // Search for type alias with that name
  for (const statement of sourceFile.statements) {
    if (ts.isTypeAliasDeclaration(statement)) {
      const name = statement.name.text;
      if (name === expectedName) {
        return name;
      }
      // Also check for Config suffix without Cwc prefix as fallback
      if (name.endsWith('Config') && !name.endsWith('ConfigSecrets')) {
        return name;
      }
    }
  }

  return undefined;
}

/**
 * Finds the secrets type name in the source file
 * Looks for patterns like CwcSqlConfigSecrets, CwcAuthConfigSecrets
 */
function findSecretsType(sourceFile: ts.SourceFile, packageName: string): string | undefined {
  const baseName = packageName.replace('cwc-', '');
  const expectedName = `Cwc${pascalCase(baseName)}ConfigSecrets`;

  for (const statement of sourceFile.statements) {
    if (ts.isTypeAliasDeclaration(statement)) {
      const name = statement.name.text;
      if (name === expectedName || name.endsWith('ConfigSecrets')) {
        return name;
      }
    }
  }

  return undefined;
}

/**
 * Finds a type node by name
 */
function findTypeNode(
  sourceFile: ts.SourceFile,
  typeName: string
): ts.TypeAliasDeclaration | undefined {
  for (const statement of sourceFile.statements) {
    if (ts.isTypeAliasDeclaration(statement) && statement.name.text === typeName) {
      return statement;
    }
  }
  return undefined;
}

/**
 * Extracts properties from type definitions
 */
function extractProperties(
  mainTypeNode: ts.TypeAliasDeclaration,
  secretsTypeNode: ts.TypeAliasDeclaration | undefined,
  sourceFile: ts.SourceFile
): { properties: ConfigProperty[]; secrets: ConfigProperty[] } {
  const properties: ConfigProperty[] = [];
  const secrets: ConfigProperty[] = [];

  // Get the type literal from the main type
  const mainTypeLiteral = getTypeLiteral(mainTypeNode);
  if (!mainTypeLiteral) {
    return { properties, secrets };
  }

  // Process each property in main type
  for (const member of mainTypeLiteral.members) {
    if (ts.isPropertySignature(member) && member.name) {
      const propName = getPropertyName(member.name);
      if (!propName) continue;

      // Skip the 'secrets' property - we handle it separately
      if (propName === 'secrets') {
        continue;
      }

      // Skip computed/derived properties (isProduction, isDevelopment, etc.)
      if (isDerivedProperty(propName)) {
        continue;
      }

      const prop = extractProperty(member, sourceFile, false);
      if (prop) {
        properties.push(prop);
      }
    }
  }

  // Process secrets type if exists
  if (secretsTypeNode) {
    const secretsTypeLiteral = getTypeLiteral(secretsTypeNode);
    if (secretsTypeLiteral) {
      for (const member of secretsTypeLiteral.members) {
        if (ts.isPropertySignature(member) && member.name) {
          const prop = extractProperty(member, sourceFile, true);
          if (prop) {
            secrets.push(prop);
          }
        }
      }
    }
  }

  return { properties, secrets };
}

/**
 * Gets the type literal from a type alias declaration
 */
function getTypeLiteral(
  typeAlias: ts.TypeAliasDeclaration
): ts.TypeLiteralNode | undefined {
  if (ts.isTypeLiteralNode(typeAlias.type)) {
    return typeAlias.type;
  }
  return undefined;
}

/**
 * Extracts a single property from a property signature
 */
function extractProperty(
  member: ts.PropertySignature,
  sourceFile: ts.SourceFile,
  isSecret: boolean
): ConfigProperty | undefined {
  const propName = getPropertyName(member.name);
  if (!propName) return undefined;

  const tsType = member.type ? getTypeString(member.type, sourceFile) : 'unknown';
  const isOptional = member.questionToken !== undefined;
  const comment = getJsDocComment(member, sourceFile);

  return {
    propertyName: propName,
    envVarName: camelToScreamingSnake(propName),
    tsType,
    isOptional,
    isSecret,
    comment,
  };
}

/**
 * Gets property name from identifier
 */
function getPropertyName(name: ts.PropertyName): string | undefined {
  if (ts.isIdentifier(name)) {
    return name.text;
  }
  if (ts.isStringLiteral(name)) {
    return name.text;
  }
  return undefined;
}

/**
 * Converts a TypeScript type node to a string representation
 */
function getTypeString(typeNode: ts.TypeNode, sourceFile: ts.SourceFile): string {
  // Handle primitive types
  if (ts.isTypeReferenceNode(typeNode)) {
    const typeName = typeNode.typeName;
    if (ts.isIdentifier(typeName)) {
      return typeName.text;
    }
  }

  // Handle literal types
  if (ts.isLiteralTypeNode(typeNode)) {
    if (typeNode.literal.kind === ts.SyntaxKind.StringKeyword) {
      return 'string';
    }
    if (typeNode.literal.kind === ts.SyntaxKind.NumericLiteral) {
      return 'number';
    }
    if (
      typeNode.literal.kind === ts.SyntaxKind.TrueKeyword ||
      typeNode.literal.kind === ts.SyntaxKind.FalseKeyword
    ) {
      return 'boolean';
    }
  }

  // Handle keyword types
  switch (typeNode.kind) {
    case ts.SyntaxKind.StringKeyword:
      return 'string';
    case ts.SyntaxKind.NumberKeyword:
      return 'number';
    case ts.SyntaxKind.BooleanKeyword:
      return 'boolean';
  }

  // Handle array types
  if (ts.isArrayTypeNode(typeNode)) {
    const elementType = getTypeString(typeNode.elementType, sourceFile);
    return `${elementType}[]`;
  }

  // Handle union types
  if (ts.isUnionTypeNode(typeNode)) {
    const types = typeNode.types.map((t) => getTypeString(t, sourceFile));
    return types.join(' | ');
  }

  // Fallback: use the printer to get the text
  const printer = ts.createPrinter();
  return printer.printNode(ts.EmitHint.Unspecified, typeNode, sourceFile);
}

/**
 * Gets JSDoc comment for a member
 */
function getJsDocComment(member: ts.PropertySignature, sourceFile: ts.SourceFile): string | undefined {
  const jsDoc = ts.getJSDocCommentsAndTags(member);
  for (const doc of jsDoc) {
    if (ts.isJSDoc(doc) && doc.comment) {
      if (typeof doc.comment === 'string') {
        return doc.comment;
      }
    }
  }

  // Try to get leading comment
  const leadingComments = ts.getLeadingCommentRanges(sourceFile.text, member.pos);
  if (leadingComments && leadingComments.length > 0) {
    const lastComment = leadingComments[leadingComments.length - 1];
    if (lastComment) {
      const commentText = sourceFile.text.slice(lastComment.pos, lastComment.end);
      // Clean up comment syntax
      return commentText
        .replace(/^\/\*\*?\s*/, '')
        .replace(/\s*\*\/$/, '')
        .replace(/^\s*\/\/\s*/, '')
        .replace(/^\s*\*\s*/gm, '')
        .trim();
    }
  }

  return undefined;
}

/**
 * Checks if a property is a derived/computed property that shouldn't have an env var
 */
function isDerivedProperty(propName: string): boolean {
  const derivedProperties = [
    // Environment flags (derived from runtimeEnvironment)
    'isProd',
    'isDev',
    'isTest',
    'isUnit',
    'isE2E',
    // Handled specially at top of env file
    'runtimeEnvironment',
    // Hardcoded in loadConfig, not from env
    'name',
  ];
  return derivedProperties.includes(propName);
}

/**
 * Converts kebab-case or snake_case to PascalCase
 */
function pascalCase(str: string): string {
  return str
    .split(/[-_]/)
    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
    .join('');
}

Version 2 (latest)

/**
 * TypeScript AST parser for extracting configuration types from config.types.ts files
 *
 * Uses the TypeScript Compiler API to parse type definitions and extract:
 * - Property names and types
 * - Optional vs required properties
 * - Nested secrets types
 * - JSDoc comments
 */

import ts from 'typescript';
import fs from 'fs';
import type { ConfigProperty, PackageConfig } from './types.js';
import { camelToScreamingSnake } from './nameConverter.js';
import type { DiscoveredPackage } from './packageDiscovery.js';

/**
 * Parses a config.types.ts file and extracts configuration schema
 *
 * @param discoveredPackage The discovered package to parse
 * @returns Parsed package configuration
 */
export function parseConfigTypes(discoveredPackage: DiscoveredPackage): PackageConfig {
  const { name: packageName, configTypesPath } = discoveredPackage;

  // Read the file
  const fileContent = fs.readFileSync(configTypesPath, 'utf-8');

  // Create a source file from the content
  const sourceFile = ts.createSourceFile(
    configTypesPath,
    fileContent,
    ts.ScriptTarget.Latest,
    true,
    ts.ScriptKind.TS
  );

  // Find the main config type and secrets type
  const configTypeName = findMainConfigType(sourceFile, packageName);
  const secretsTypeName = findSecretsType(sourceFile, packageName);

  if (!configTypeName) {
    throw new Error(
      `Could not find main config type in ${configTypesPath}. ` +
        `Expected a type like 'Cwc${pascalCase(packageName.replace('cwc-', ''))}Config'`
    );
  }

  // Extract properties from main config type
  const mainTypeNode = findTypeNode(sourceFile, configTypeName);
  if (!mainTypeNode) {
    throw new Error(`Could not find type definition for ${configTypeName}`);
  }

  // Extract properties from secrets type if exists
  let secretsTypeNode: ts.TypeAliasDeclaration | undefined;
  if (secretsTypeName) {
    secretsTypeNode = findTypeNode(sourceFile, secretsTypeName);
  }

  // Parse properties
  const { properties, secrets } = extractProperties(mainTypeNode, secretsTypeNode, sourceFile);

  return {
    packageName,
    configTypesPath,
    configTypeName,
    secretsTypeName,
    properties,
    secrets,
  };
}

/**
 * Finds the main config type name in the source file
 * Looks for patterns like CwcSqlConfig, CwcAuthConfig, CwcStorageConfig
 */
function findMainConfigType(sourceFile: ts.SourceFile, packageName: string): string | undefined {
  // Build expected type name from package name
  // cwc-sql -> CwcSqlConfig
  // cwc-auth -> CwcAuthConfig
  // cwc-backend-utils -> CwcBackendUtilsConfig
  const baseName = packageName.replace('cwc-', '');
  const expectedName = `Cwc${pascalCase(baseName)}Config`;

  // Search for type alias with that name
  for (const statement of sourceFile.statements) {
    if (ts.isTypeAliasDeclaration(statement)) {
      const name = statement.name.text;
      if (name === expectedName) {
        return name;
      }
      // Also check for Config suffix without Cwc prefix as fallback
      if (name.endsWith('Config') && !name.endsWith('ConfigSecrets')) {
        return name;
      }
    }
  }

  return undefined;
}

/**
 * Finds the secrets type name in the source file
 * Looks for patterns like CwcSqlConfigSecrets, CwcAuthConfigSecrets
 */
function findSecretsType(sourceFile: ts.SourceFile, packageName: string): string | undefined {
  const baseName = packageName.replace('cwc-', '');
  const expectedName = `Cwc${pascalCase(baseName)}ConfigSecrets`;

  for (const statement of sourceFile.statements) {
    if (ts.isTypeAliasDeclaration(statement)) {
      const name = statement.name.text;
      if (name === expectedName || name.endsWith('ConfigSecrets')) {
        return name;
      }
    }
  }

  return undefined;
}

/**
 * Finds a type node by name
 */
function findTypeNode(
  sourceFile: ts.SourceFile,
  typeName: string
): ts.TypeAliasDeclaration | undefined {
  for (const statement of sourceFile.statements) {
    if (ts.isTypeAliasDeclaration(statement) && statement.name.text === typeName) {
      return statement;
    }
  }
  return undefined;
}

/**
 * Extracts properties from type definitions
 */
function extractProperties(
  mainTypeNode: ts.TypeAliasDeclaration,
  secretsTypeNode: ts.TypeAliasDeclaration | undefined,
  sourceFile: ts.SourceFile
): { properties: ConfigProperty[]; secrets: ConfigProperty[] } {
  const properties: ConfigProperty[] = [];
  const secrets: ConfigProperty[] = [];

  // Get the type literal from the main type
  const mainTypeLiteral = getTypeLiteral(mainTypeNode);
  if (!mainTypeLiteral) {
    return { properties, secrets };
  }

  // Process each property in main type
  for (const member of mainTypeLiteral.members) {
    if (ts.isPropertySignature(member) && member.name) {
      const propName = getPropertyName(member.name);
      if (!propName) continue;

      // Skip the 'secrets' property - we handle it separately
      if (propName === 'secrets') {
        continue;
      }

      // Skip computed/derived properties (isProd, isDev, etc.)
      if (isDerivedProperty(propName)) {
        continue;
      }

      const prop = extractProperty(member, sourceFile, false);
      if (prop) {
        properties.push(prop);
      }
    }
  }

  // Process secrets type if exists
  if (secretsTypeNode) {
    const secretsTypeLiteral = getTypeLiteral(secretsTypeNode);
    if (secretsTypeLiteral) {
      for (const member of secretsTypeLiteral.members) {
        if (ts.isPropertySignature(member) && member.name) {
          const prop = extractProperty(member, sourceFile, true);
          if (prop) {
            secrets.push(prop);
          }
        }
      }
    }
  }

  return { properties, secrets };
}

/**
 * Gets the type literal from a type alias declaration
 */
function getTypeLiteral(typeAlias: ts.TypeAliasDeclaration): ts.TypeLiteralNode | undefined {
  if (ts.isTypeLiteralNode(typeAlias.type)) {
    return typeAlias.type;
  }
  return undefined;
}

/**
 * Extracts a single property from a property signature
 */
function extractProperty(
  member: ts.PropertySignature,
  sourceFile: ts.SourceFile,
  isSecret: boolean
): ConfigProperty | undefined {
  const propName = getPropertyName(member.name);
  if (!propName) return undefined;

  const tsType = member.type ? getTypeString(member.type, sourceFile) : 'unknown';
  const isOptional = member.questionToken !== undefined;
  const comment = getJsDocComment(member, sourceFile);

  return {
    propertyName: propName,
    envVarName: camelToScreamingSnake(propName),
    tsType,
    isOptional,
    isSecret,
    comment,
  };
}

/**
 * Gets property name from identifier
 */
function getPropertyName(name: ts.PropertyName): string | undefined {
  if (ts.isIdentifier(name)) {
    return name.text;
  }
  if (ts.isStringLiteral(name)) {
    return name.text;
  }
  return undefined;
}

/**
 * Converts a TypeScript type node to a string representation
 */
function getTypeString(typeNode: ts.TypeNode, sourceFile: ts.SourceFile): string {
  // Handle primitive types
  if (ts.isTypeReferenceNode(typeNode)) {
    const typeName = typeNode.typeName;
    if (ts.isIdentifier(typeName)) {
      return typeName.text;
    }
  }

  // Handle literal types
  if (ts.isLiteralTypeNode(typeNode)) {
    if (typeNode.literal.kind === ts.SyntaxKind.StringKeyword) {
      return 'string';
    }
    if (typeNode.literal.kind === ts.SyntaxKind.NumericLiteral) {
      return 'number';
    }
    if (
      typeNode.literal.kind === ts.SyntaxKind.TrueKeyword ||
      typeNode.literal.kind === ts.SyntaxKind.FalseKeyword
    ) {
      return 'boolean';
    }
  }

  // Handle keyword types
  switch (typeNode.kind) {
    case ts.SyntaxKind.StringKeyword:
      return 'string';
    case ts.SyntaxKind.NumberKeyword:
      return 'number';
    case ts.SyntaxKind.BooleanKeyword:
      return 'boolean';
  }

  // Handle array types
  if (ts.isArrayTypeNode(typeNode)) {
    const elementType = getTypeString(typeNode.elementType, sourceFile);
    return `${elementType}[]`;
  }

  // Handle union types
  if (ts.isUnionTypeNode(typeNode)) {
    const types = typeNode.types.map((t) => getTypeString(t, sourceFile));
    return types.join(' | ');
  }

  // Fallback: use the printer to get the text
  const printer = ts.createPrinter();
  return printer.printNode(ts.EmitHint.Unspecified, typeNode, sourceFile);
}

/**
 * Gets JSDoc comment for a member
 */
function getJsDocComment(
  member: ts.PropertySignature,
  sourceFile: ts.SourceFile
): string | undefined {
  const jsDoc = ts.getJSDocCommentsAndTags(member);
  for (const doc of jsDoc) {
    if (ts.isJSDoc(doc) && doc.comment) {
      if (typeof doc.comment === 'string') {
        return doc.comment;
      }
    }
  }

  // Try to get leading comment
  const leadingComments = ts.getLeadingCommentRanges(sourceFile.text, member.pos);
  if (leadingComments && leadingComments.length > 0) {
    const lastComment = leadingComments[leadingComments.length - 1];
    if (lastComment) {
      const commentText = sourceFile.text.slice(lastComment.pos, lastComment.end);
      // Clean up comment syntax
      return commentText
        .replace(/^\/\*\*?\s*/, '')
        .replace(/\s*\*\/$/, '')
        .replace(/^\s*\/\/\s*/, '')
        .replace(/^\s*\*\s*/gm, '')
        .trim();
    }
  }

  return undefined;
}

/**
 * Checks if a property is a derived/computed property that shouldn't have an env var
 */
function isDerivedProperty(propName: string): boolean {
  const derivedProperties = [
    // Environment flags (derived from runtimeEnvironment)
    'isProd',
    'isDev',
    'isTest',
    'isUnit',
    'isE2E',
    // Handled specially at top of env file
    'runtimeEnvironment',
    // Hardcoded in loadConfig, not from env
    'name',
  ];
  return derivedProperties.includes(propName);
}

/**
 * Converts kebab-case or snake_case to PascalCase
 */
function pascalCase(str: string): string {
  return str
    .split(/[-_]/)
    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
    .join('');
}

packages/cwc-sql/src/__tests__/config.test.ts

2 versions

Version 1

import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';

describe('Configuration Loading', () => {
  let originalEnv: NodeJS.ProcessEnv;
  let exitSpy: jest.SpiedFunction<typeof process.exit>;

  beforeEach(() => {
    // Save original environment
    originalEnv = { ...process.env };

    // Mock process.exit to prevent test termination
    exitSpy = jest.spyOn(process, 'exit').mockImplementation((code?: string | number) => {
      throw new Error(`process.exit called with ${code}`);
    }) as jest.SpiedFunction<typeof process.exit>;

    // Clear environment
    delete process.env.RUNTIME_ENVIRONMENT;
    delete process.env.SERVICE_PORT;
    delete process.env.DATABASE_SERVER;
    delete process.env.DATABASE_NAME;
    delete process.env.DATABASE_USER;
    delete process.env.DATABASE_PASSWORD;
    delete process.env.DATABASE_CONNECT_TIMEOUT;
    delete process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT;
    delete process.env.DATABASE_CONNECTION_QUEUE_LIMIT;
    delete process.env.DATABASE_CONNECTION_LIMIT;
    delete process.env.SQL_CLIENT_API_KEY;
    delete process.env.DEBUG_MODE;
    delete process.env.LOG_ERRORS_TO_DATABASE;
    delete process.env.QUERY_CACHE_ENABLED;
    delete process.env.QUERY_CACHE_TTL;
    delete process.env.QUERY_CACHE_MAX_KEYS;
    delete process.env.CORS_ORIGIN;
    delete process.env.RATE_LIMITER_POINTS;
    delete process.env.RATE_LIMITER_DURATION;
    delete process.env.END_TO_END_TESTING_MOCK_VALUES;

    // Clear module cache to ensure fresh import
    jest.resetModules();
  });

  afterEach(() => {
    // Restore original environment
    process.env = originalEnv;

    // Restore process.exit
    exitSpy.mockRestore();
  });

  it('should load valid configuration', async () => {
    // Set valid environment variables
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = '-----BEGIN PUBLIC KEY-----\\nTEST\\n-----END PUBLIC KEY-----';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'ON';
    process.env.LOG_ERRORS_TO_DATABASE = 'ON';
    process.env.QUERY_CACHE_ENABLED = 'ON';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.RATE_LIMITER_POINTS = '150';
    process.env.RATE_LIMITER_DURATION = '90';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.runtimeEnvironment).toBe('dev');
    expect(config.isDev).toBe(true);
    expect(config.isProd).toBe(false);
    expect(config.isTest).toBe(false);
    expect(config.servicePort).toBe(5003);
    expect(config.databaseServer).toBe('localhost');
    expect(config.databaseName).toBe('test_db');
    expect(config.secrets.databaseUser).toBe('test_user');
    expect(config.secrets.databasePassword).toBe('test_password');
    expect(config.secrets.sqlClientApiKey).toContain('-----BEGIN PUBLIC KEY-----');
    expect(config.debugMode).toBe(true);
    expect(config.logErrorsToDatabase).toBe(true);
    expect(config.queryCacheEnabled).toBe(true);
    expect(config.queryCacheTtl).toBe(5);
    expect(config.queryCacheMaxKeys).toBe(1000);
    expect(config.corsOrigin).toBe('http://localhost:3000');
    expect(config.rateLimiterPoints).toBe(150);
    expect(config.rateLimiterDuration).toBe(90);
    expect(config.endToEndMockValues).toBeUndefined();
  });

  it('should parse production environment correctly', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'prod';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'db.example.com';
    process.env.DATABASE_NAME = 'prod_db';
    process.env.DATABASE_USER = 'prod_user';
    process.env.DATABASE_PASSWORD = 'prod_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '10';
    process.env.QUERY_CACHE_MAX_KEYS = '5000';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.runtimeEnvironment).toBe('prod');
    expect(config.isProduction).toBe(true);
    expect(config.isDevelopment).toBe(false);
    expect(config.isTest).toBe(false);
    expect(config.debugMode).toBe(false);
  });

  it('should use default SERVICE_PORT if not provided', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    // SERVICE_PORT not set
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.servicePort).toBe(5003); // Default value
  });

  it('should parse multi-line public key with escaped newlines', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = '-----BEGIN PUBLIC KEY-----\\nLINE1\\nLINE2\\n-----END PUBLIC KEY-----';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    // Should convert \\n to actual newlines
    expect(config.secrets.sqlClientApiKey).toContain('\n');
    expect(config.secrets.sqlClientApiKey).not.toContain('\\n');
  });

  it('should call process.exit for missing required RUNTIME_ENVIRONMENT', async () => {
    // Don't set RUNTIME_ENVIRONMENT
    process.env.SERVICE_PORT = '5003';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid RUNTIME_ENVIRONMENT', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'invalid';
    process.env.SERVICE_PORT = '5003';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for missing DATABASE_SERVER', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    // DATABASE_SERVER not set

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid number in SERVICE_PORT', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = 'not-a-number';
    process.env.DATABASE_SERVER = 'localhost';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid SERVICE_PORT range', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '99999'; // Too high
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid database timeout values', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '-1'; // Invalid
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid cache settings when enabled', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'ON';
    process.env.QUERY_CACHE_TTL = '-5'; // Invalid
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should cache configuration on subsequent calls', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');
    const config1 = loadConfig();
    const config2 = loadConfig();

    // Should return the same cached instance
    expect(config1).toBe(config2);
  });

  it('should use default rate limiter values when not provided', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';
    // RATE_LIMITER_* not set

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.rateLimiterPoints).toBe(100); // Default value
    expect(config.rateLimiterDuration).toBe(60); // Default value
  });

  it('should call process.exit for missing required CORS_ORIGIN', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    // CORS_ORIGIN not set
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should parse END_TO_END_TESTING_MOCK_VALUES in e2e environment', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'e2e';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';
    process.env.END_TO_END_TESTING_MOCK_VALUES = '{"userPkId":"12345","deviceId":"test-device"}';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.runtimeEnvironment).toBe('e2e');
    expect(config.isEndToEnd).toBe(true);
    expect(config.endToEndMockValues).toEqual({
      userPkId: '12345',
      deviceId: 'test-device',
    });
  });

  it('should ignore END_TO_END_TESTING_MOCK_VALUES in non-e2e environment', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';
    process.env.END_TO_END_TESTING_MOCK_VALUES = '{"userPkId":"12345"}'; // Should be ignored

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.runtimeEnvironment).toBe('dev');
    expect(config.isEndToEnd).toBe(false);
    expect(config.endToEndMockValues).toBeUndefined();
  });
});

Version 2 (latest)

import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';

describe('Configuration Loading', () => {
  let originalEnv: NodeJS.ProcessEnv;
  let exitSpy: jest.SpiedFunction<typeof process.exit>;

  beforeEach(() => {
    // Save original environment
    originalEnv = { ...process.env };

    // Mock process.exit to prevent test termination
    exitSpy = jest.spyOn(process, 'exit').mockImplementation((code?: string | number) => {
      throw new Error(`process.exit called with ${code}`);
    }) as jest.SpiedFunction<typeof process.exit>;

    // Clear environment
    delete process.env.RUNTIME_ENVIRONMENT;
    delete process.env.SERVICE_PORT;
    delete process.env.DATABASE_SERVER;
    delete process.env.DATABASE_NAME;
    delete process.env.DATABASE_USER;
    delete process.env.DATABASE_PASSWORD;
    delete process.env.DATABASE_CONNECT_TIMEOUT;
    delete process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT;
    delete process.env.DATABASE_CONNECTION_QUEUE_LIMIT;
    delete process.env.DATABASE_CONNECTION_LIMIT;
    delete process.env.SQL_CLIENT_API_KEY;
    delete process.env.DEBUG_MODE;
    delete process.env.LOG_ERRORS_TO_DATABASE;
    delete process.env.QUERY_CACHE_ENABLED;
    delete process.env.QUERY_CACHE_TTL;
    delete process.env.QUERY_CACHE_MAX_KEYS;
    delete process.env.CORS_ORIGIN;
    delete process.env.RATE_LIMITER_POINTS;
    delete process.env.RATE_LIMITER_DURATION;
    delete process.env.END_TO_END_TESTING_MOCK_VALUES;

    // Clear module cache to ensure fresh import
    jest.resetModules();
  });

  afterEach(() => {
    // Restore original environment
    process.env = originalEnv;

    // Restore process.exit
    exitSpy.mockRestore();
  });

  it('should load valid configuration', async () => {
    // Set valid environment variables
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = '-----BEGIN PUBLIC KEY-----\\nTEST\\n-----END PUBLIC KEY-----';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'ON';
    process.env.LOG_ERRORS_TO_DATABASE = 'ON';
    process.env.QUERY_CACHE_ENABLED = 'ON';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.RATE_LIMITER_POINTS = '150';
    process.env.RATE_LIMITER_DURATION = '90';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.runtimeEnvironment).toBe('dev');
    expect(config.isDev).toBe(true);
    expect(config.isProd).toBe(false);
    expect(config.isTest).toBe(false);
    expect(config.servicePort).toBe(5003);
    expect(config.databaseServer).toBe('localhost');
    expect(config.databaseName).toBe('test_db');
    expect(config.secrets.databaseUser).toBe('test_user');
    expect(config.secrets.databasePassword).toBe('test_password');
    expect(config.secrets.sqlClientApiKey).toContain('-----BEGIN PUBLIC KEY-----');
    expect(config.debugMode).toBe(true);
    expect(config.logErrorsToDatabase).toBe(true);
    expect(config.queryCacheEnabled).toBe(true);
    expect(config.queryCacheTtl).toBe(5);
    expect(config.queryCacheMaxKeys).toBe(1000);
    expect(config.corsOrigin).toBe('http://localhost:3000');
    expect(config.rateLimiterPoints).toBe(150);
    expect(config.rateLimiterDuration).toBe(90);
    expect(config.endToEndMockValues).toBeUndefined();
  });

  it('should parse production environment correctly', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'prod';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'db.example.com';
    process.env.DATABASE_NAME = 'prod_db';
    process.env.DATABASE_USER = 'prod_user';
    process.env.DATABASE_PASSWORD = 'prod_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '10';
    process.env.QUERY_CACHE_MAX_KEYS = '5000';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.runtimeEnvironment).toBe('prod');
    expect(config.isProd).toBe(true);
    expect(config.isDev).toBe(false);
    expect(config.isTest).toBe(false);
    expect(config.debugMode).toBe(false);
  });

  it('should use default SERVICE_PORT if not provided', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    // SERVICE_PORT not set
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.servicePort).toBe(5003); // Default value
  });

  it('should parse multi-line public key with escaped newlines', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = '-----BEGIN PUBLIC KEY-----\\nLINE1\\nLINE2\\n-----END PUBLIC KEY-----';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    // Should convert \\n to actual newlines
    expect(config.secrets.sqlClientApiKey).toContain('\n');
    expect(config.secrets.sqlClientApiKey).not.toContain('\\n');
  });

  it('should call process.exit for missing required RUNTIME_ENVIRONMENT', async () => {
    // Don't set RUNTIME_ENVIRONMENT
    process.env.SERVICE_PORT = '5003';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid RUNTIME_ENVIRONMENT', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'invalid';
    process.env.SERVICE_PORT = '5003';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for missing DATABASE_SERVER', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    // DATABASE_SERVER not set

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid number in SERVICE_PORT', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = 'not-a-number';
    process.env.DATABASE_SERVER = 'localhost';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid SERVICE_PORT range', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '99999'; // Too high
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid database timeout values', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '-1'; // Invalid
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should call process.exit for invalid cache settings when enabled', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'ON';
    process.env.QUERY_CACHE_TTL = '-5'; // Invalid
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should cache configuration on subsequent calls', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');
    const config1 = loadConfig();
    const config2 = loadConfig();

    // Should return the same cached instance
    expect(config1).toBe(config2);
  });

  it('should use default rate limiter values when not provided', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';
    // RATE_LIMITER_* not set

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.rateLimiterPoints).toBe(100); // Default value
    expect(config.rateLimiterDuration).toBe(60); // Default value
  });

  it('should call process.exit for missing required CORS_ORIGIN', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    // CORS_ORIGIN not set
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';

    const { loadConfig } = await import('../config/loadConfig');

    expect(() => loadConfig()).toThrow('process.exit called with 1');
    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should parse END_TO_END_TESTING_MOCK_VALUES in e2e environment', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'e2e';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';
    process.env.END_TO_END_TESTING_MOCK_VALUES = '{"userPkId":"12345","deviceId":"test-device"}';

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.runtimeEnvironment).toBe('e2e');
    expect(config.isE2E).toBe(true);
    expect(config.endToEndMockValues).toEqual({
      userPkId: '12345',
      deviceId: 'test-device',
    });
  });

  it('should ignore END_TO_END_TESTING_MOCK_VALUES in non-e2e environment', async () => {
    process.env.RUNTIME_ENVIRONMENT = 'dev';
    process.env.SERVICE_PORT = '5003';
    process.env.DATABASE_SERVER = 'localhost';
    process.env.DATABASE_NAME = 'test_db';
    process.env.DATABASE_USER = 'test_user';
    process.env.DATABASE_PASSWORD = 'test_password';
    process.env.DATABASE_CONNECT_TIMEOUT = '10000';
    process.env.DATABASE_CONNECTION_ACQUIRE_TIMEOUT = '30000';
    process.env.DATABASE_CONNECTION_QUEUE_LIMIT = '1000';
    process.env.DATABASE_CONNECTION_LIMIT = '20';
    process.env.SQL_CLIENT_API_KEY = 'test-key';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.CORS_ORIGIN = 'http://localhost:3000';
    process.env.DEBUG_MODE = 'OFF';
    process.env.LOG_ERRORS_TO_DATABASE = 'OFF';
    process.env.QUERY_CACHE_ENABLED = 'OFF';
    process.env.QUERY_CACHE_TTL = '5';
    process.env.QUERY_CACHE_MAX_KEYS = '1000';
    process.env.END_TO_END_TESTING_MOCK_VALUES = '{"userPkId":"12345"}'; // Should be ignored

    const { loadConfig } = await import('../config/loadConfig');
    const config = loadConfig();

    expect(config.runtimeEnvironment).toBe('dev');
    expect(config.isE2E).toBe(false);
    expect(config.endToEndMockValues).toBeUndefined();
  });
});

packages/cwc-sql/src/__tests__/queryCache.test.ts

import { describe, it, expect, beforeEach } from '@jest/globals';
import { QueryCache } from '../cache/queryCache';
import type { CwcSqlConfig } from '../config';
import type { SqlClientOperation } from 'cwc-backend-utils';

describe('QueryCache', () => {
  let config: CwcSqlConfig;
  let cache: QueryCache;

  beforeEach(() => {
    config = {
      runtimeEnvironment: 'unit',
      isProd: false,
      isDev: false,
      isTest: false,
      isUnit: true,
      isE2E: false,
      servicePort: 5003,
      databaseServer: 'localhost',
      databaseName: 'test',
      databaseUser: 'test',
      databasePassword: 'test',
      databaseConnectTimeout: 10000,
      databaseConnectionAcquireTimeout: 30000,
      databaseConnectionQueueLimit: 1000,
      databaseConnectionLimit: 20,
      sqlClientApiKey: 'test-key',
      debugMode: false,
      logErrorsToDatabase: false,
      queryCacheEnabled: true,
      queryCacheTtl: 5,
      queryCacheMaxKeys: 1000,
    };

    cache = new QueryCache(config);
  });

  it('should cache SELECT operation result', () => {
    const operation: SqlClientOperation = {
      operationType: 'select',
      table: 'user',
      filters: { email: 'test@example.com' },
    };

    const data = [{ userPkId: 1, email: 'test@example.com' }];

    // Set cache
    cache.set(operation, data);

    // Get cache
    const cached = cache.get(operation);

    expect(cached).toEqual(data);
  });

  it('should return undefined for cache miss', () => {
    const operation: SqlClientOperation = {
      operationType: 'select',
      table: 'user',
      filters: { email: 'test@example.com' },
    };

    const cached = cache.get(operation);

    expect(cached).toBeUndefined();
  });

  it('should not cache non-SELECT operations', () => {
    const operation: SqlClientOperation = {
      operationType: 'insert',
      table: 'user',
      values: { username: 'test' },
    };

    const data = { insertId: 123 };

    cache.set(operation, data);
    const cached = cache.get(operation);

    expect(cached).toBeUndefined();
  });

  it('should generate different cache keys for different operations', () => {
    const operation1: SqlClientOperation = {
      operationType: 'select',
      table: 'user',
      filters: { email: 'test1@example.com' },
    };

    const operation2: SqlClientOperation = {
      operationType: 'select',
      table: 'user',
      filters: { email: 'test2@example.com' },
    };

    cache.set(operation1, [{ id: 1 }]);
    cache.set(operation2, [{ id: 2 }]);

    const cached1 = cache.get(operation1);
    const cached2 = cache.get(operation2);

    expect(cached1).toEqual([{ id: 1 }]);
    expect(cached2).toEqual([{ id: 2 }]);
  });

  it('should invalidate cache for specific table', () => {
    const operation1: SqlClientOperation = {
      operationType: 'select',
      table: 'user',
      filters: { email: 'test@example.com' },
    };

    const operation2: SqlClientOperation = {
      operationType: 'select',
      table: 'project',
      filters: { title: 'Test Project' },
    };

    cache.set(operation1, [{ id: 1 }]);
    cache.set(operation2, [{ id: 2 }]);

    // Invalidate user table
    cache.invalidateTable('user');

    // User cache should be cleared
    expect(cache.get(operation1)).toBeUndefined();

    // Project cache should remain
    expect(cache.get(operation2)).toEqual([{ id: 2 }]);
  });

  it('should invalidate cache for multiple tables', () => {
    const operation1: SqlClientOperation = {
      operationType: 'select',
      table: 'user',
      filters: { email: 'test@example.com' },
    };

    const operation2: SqlClientOperation = {
      operationType: 'select',
      table: 'project',
      filters: { title: 'Test Project' },
    };

    const operation3: SqlClientOperation = {
      operationType: 'select',
      table: 'comment',
      filters: { content: 'Test Comment' },
    };

    cache.set(operation1, [{ id: 1 }]);
    cache.set(operation2, [{ id: 2 }]);
    cache.set(operation3, [{ id: 3 }]);

    // Invalidate user and project tables
    cache.invalidateTables(['user', 'project']);

    // User and project caches should be cleared
    expect(cache.get(operation1)).toBeUndefined();
    expect(cache.get(operation2)).toBeUndefined();

    // Comment cache should remain
    expect(cache.get(operation3)).toEqual([{ id: 3 }]);
  });

  it('should track custom tables for invalidation', () => {
    const operation: SqlClientOperation = {
      operationType: 'select',
      custom: {
        customSql: 'SELECT * FROM user JOIN project ON ...',
        customParams: {},
        customTables: ['user', 'project'],
      },
    };

    cache.set(operation, [{ id: 1 }]);

    // Invalidating either table should clear the cache
    cache.invalidateTable('user');

    expect(cache.get(operation)).toBeUndefined();
  });

  it('should clear entire cache', () => {
    const operation1: SqlClientOperation = {
      operationType: 'select',
      table: 'user',
      filters: { email: 'test@example.com' },
    };

    const operation2: SqlClientOperation = {
      operationType: 'select',
      table: 'project',
      filters: { title: 'Test Project' },
    };

    cache.set(operation1, [{ id: 1 }]);
    cache.set(operation2, [{ id: 2 }]);

    // Clear all cache
    cache.clear();

    expect(cache.get(operation1)).toBeUndefined();
    expect(cache.get(operation2)).toBeUndefined();
  });

  it('should not cache when caching is disabled', () => {
    const disabledConfig = { ...config, queryCacheEnabled: false };
    const disabledCache = new QueryCache(disabledConfig);

    const operation: SqlClientOperation = {
      operationType: 'select',
      table: 'user',
      filters: { email: 'test@example.com' },
    };

    disabledCache.set(operation, [{ id: 1 }]);
    const cached = disabledCache.get(operation);

    expect(cached).toBeUndefined();
  });

  it('should return cache statistics', () => {
    const operation1: SqlClientOperation = {
      operationType: 'select',
      table: 'user',
      filters: { email: 'test@example.com' },
    };

    const operation2: SqlClientOperation = {
      operationType: 'select',
      table: 'project',
      filters: { title: 'Test Project' },
    };

    cache.set(operation1, [{ id: 1 }]);
    cache.set(operation2, [{ id: 2 }]);

    // Trigger cache hits and misses
    cache.get(operation1); // Hit
    cache.get(operation1); // Hit
    cache.get({ operationType: 'select', table: 'comment' }); // Miss

    const stats = cache.getStats();

    expect(stats.keys).toBe(2);
    expect(stats.hits).toBeGreaterThan(0);
    expect(stats.misses).toBeGreaterThan(0);
    expect(stats.tables).toBe(2);
  });
});

packages/cwc-sql/src/config/config.types.ts

import type { RuntimeEnvironment } from 'cwc-types';

/**
 * Secret configuration values for cwc-sql
 * These values must be provided via secrets file, never committed to code
 */
export type CwcSqlConfigSecrets = {
  databaseUser: string;
  databasePassword: string;
  sqlClientApiKey: string;
};

/**
 * Configuration for the cwc-sql microservice
 */
export type CwcSqlConfig = {
  // Environment
  runtimeEnvironment: RuntimeEnvironment;
  isProd: boolean;
  isDev: boolean;
  isTest: boolean;
  isUnit: boolean;
  isE2E: boolean;

  // Service
  servicePort: number;

  // Database connection
  databaseServer: string;
  databaseName: string;
  databaseConnectTimeout: number;
  databaseConnectionAcquireTimeout: number;
  databaseConnectionQueueLimit: number;
  databaseConnectionLimit: number;

  // Security
  corsOrigin: string;

  // Rate limiting
  rateLimiterPoints: number;
  rateLimiterDuration: number;

  // Debugging
  debugMode: boolean;
  logErrorsToDatabase: boolean;

  // Query caching
  queryCacheEnabled: boolean;
  queryCacheTtl: number;
  queryCacheMaxKeys: number;

  // End-to-end testing mock values
  endToEndMockValues?: Record<string, string>;

  // Secrets (nested)
  secrets: CwcSqlConfigSecrets;
};

packages/cwc-sql/src/config/loadConfig.ts

2 versions

Version 1

import type { RuntimeEnvironment } from 'cwc-types';
import type { CwcSqlConfig } from './config.types';

/**
 * Validates that a required environment variable is present
 */
function requireEnv(name: string): string {
  const value = process.env[name];
  if (value === undefined || value === '') {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

/**
 * Parses an environment variable as a number
 */
function parseNumber(name: string, defaultValue?: number): number {
  const value = process.env[name];
  if (value === undefined || value === '') {
    if (defaultValue !== undefined) {
      return defaultValue;
    }
    throw new Error(`Missing required environment variable: ${name}`);
  }

  const parsed = Number(value);
  if (isNaN(parsed)) {
    throw new Error(`Environment variable ${name} must be a number, got: ${value}`);
  }
  return parsed;
}

/**
 * Parses an environment variable as a boolean (ON/OFF)
 */
function parseBoolean(name: string, defaultValue: boolean = false): boolean {
  const value = process.env[name];
  if (value === undefined || value === '') {
    return defaultValue;
  }

  const upper = value.toUpperCase();
  if (upper === 'ON' || upper === 'TRUE' || upper === '1') {
    return true;
  }
  if (upper === 'OFF' || upper === 'FALSE' || upper === '0') {
    return false;
  }

  throw new Error(`Environment variable ${name} must be ON/OFF, got: ${value}`);
}

/**
 * Parses multi-line public key from environment variable
 * Environment variables escape newlines as \n, so we need to convert them
 */
function parsePublicKey(name: string): string {
  const value = requireEnv(name);

  // Replace escaped \n with actual newlines
  return value.replace(/\\n/g, '\n');
}

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcSqlConfig | undefined;

export function loadConfig(): CwcSqlConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProd = runtimeEnvironment === 'prod';
    const isDev = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnit = runtimeEnvironment === 'unit';
    const isE2E = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcSqlConfig = {
      // Environment
      runtimeEnvironment,
      isProd,
      isDev,
      isTest,
      isUnit,
      isE2E,

      // Service
      servicePort: parseNumber('SERVICE_PORT', 5003),

      // Database connection
      databaseServer: requireEnv('DATABASE_SERVER'),
      databaseName: requireEnv('DATABASE_NAME'),
      databaseConnectTimeout: parseNumber('DATABASE_CONNECT_TIMEOUT'),
      databaseConnectionAcquireTimeout: parseNumber('DATABASE_CONNECTION_ACQUIRE_TIMEOUT'),
      databaseConnectionQueueLimit: parseNumber('DATABASE_CONNECTION_QUEUE_LIMIT'),
      databaseConnectionLimit: parseNumber('DATABASE_CONNECTION_LIMIT'),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),

      // Rate limiting
      // RATE_LIMITER_POINTS: Maximum number of requests allowed per duration
      // RATE_LIMITER_DURATION: Time window in seconds
      // Example: 100 points / 60 seconds = max 100 requests per minute per IP
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 100),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 60),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE'),
      logErrorsToDatabase: parseBoolean('LOG_ERRORS_TO_DATABASE'),

      // Query caching
      queryCacheEnabled: parseBoolean('QUERY_CACHE_ENABLED'),
      queryCacheTtl: parseNumber('QUERY_CACHE_TTL'),
      queryCacheMaxKeys: parseNumber('QUERY_CACHE_MAX_KEYS'),

      // End-to-end testing (optional, only in e2e environment)
      endToEndMockValues:
        isEndToEnd && process.env['END_TO_END_TESTING_MOCK_VALUES']
          ? JSON.parse(process.env['END_TO_END_TESTING_MOCK_VALUES'])
          : undefined,

      // Secrets (nested)
      secrets: {
        databaseUser: requireEnv('DATABASE_USER'),
        databasePassword: requireEnv('DATABASE_PASSWORD'),
        sqlClientApiKey: parsePublicKey('SQL_CLIENT_API_KEY'),
      },
    };

    // Validate database connection settings
    if (config.databaseConnectTimeout <= 0) {
      throw new Error('DATABASE_CONNECT_TIMEOUT must be greater than 0');
    }
    if (config.databaseConnectionAcquireTimeout <= 0) {
      throw new Error('DATABASE_CONNECTION_ACQUIRE_TIMEOUT must be greater than 0');
    }
    if (config.databaseConnectionQueueLimit <= 0) {
      throw new Error('DATABASE_CONNECTION_QUEUE_LIMIT must be greater than 0');
    }
    if (config.databaseConnectionLimit <= 0) {
      throw new Error('DATABASE_CONNECTION_LIMIT must be greater than 0');
    }

    // Validate cache settings
    if (config.queryCacheEnabled) {
      if (config.queryCacheTtl <= 0) {
        throw new Error('QUERY_CACHE_TTL must be greater than 0');
      }
      if (config.queryCacheMaxKeys <= 0) {
        throw new Error('QUERY_CACHE_MAX_KEYS must be greater than 0');
      }
    }

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-sql] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  Database Server: ${config.databaseServer}`);
      console.log(`  Database Name: ${config.databaseName}`);
      console.log(`  Database User: [REDACTED]`);
      console.log(`  Database Password: [REDACTED]`);
      console.log(`  Database Connect Timeout: ${config.databaseConnectTimeout}ms`);
      console.log(`  Database Connection Acquire Timeout: ${config.databaseConnectionAcquireTimeout}ms`);
      console.log(`  Database Connection Queue Limit: ${config.databaseConnectionQueueLimit}`);
      console.log(`  Database Connection Limit: ${config.databaseConnectionLimit}`);
      console.log(`  SQL Client API Key: [REDACTED]`);
      console.log(`  Debug Mode: ${config.debugMode}`);
      console.log(`  Log Errors to Database: ${config.logErrorsToDatabase}`);
      console.log(`  Query Cache Enabled: ${config.queryCacheEnabled}`);
      if (config.queryCacheEnabled) {
        console.log(`  Query Cache TTL: ${config.queryCacheTtl} minutes`);
        console.log(`  Query Cache Max Keys: ${config.queryCacheMaxKeys}`);
      }
    }

    return config;
  } catch (error) {
    console.error('[cwc-sql] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

Version 2 (latest)

import type { RuntimeEnvironment } from 'cwc-types';
import type { CwcSqlConfig } from './config.types';

/**
 * Validates that a required environment variable is present
 */
function requireEnv(name: string): string {
  const value = process.env[name];
  if (value === undefined || value === '') {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

/**
 * Parses an environment variable as a number
 */
function parseNumber(name: string, defaultValue?: number): number {
  const value = process.env[name];
  if (value === undefined || value === '') {
    if (defaultValue !== undefined) {
      return defaultValue;
    }
    throw new Error(`Missing required environment variable: ${name}`);
  }

  const parsed = Number(value);
  if (isNaN(parsed)) {
    throw new Error(`Environment variable ${name} must be a number, got: ${value}`);
  }
  return parsed;
}

/**
 * Parses an environment variable as a boolean (ON/OFF)
 */
function parseBoolean(name: string, defaultValue: boolean = false): boolean {
  const value = process.env[name];
  if (value === undefined || value === '') {
    return defaultValue;
  }

  const upper = value.toUpperCase();
  if (upper === 'ON' || upper === 'TRUE' || upper === '1') {
    return true;
  }
  if (upper === 'OFF' || upper === 'FALSE' || upper === '0') {
    return false;
  }

  throw new Error(`Environment variable ${name} must be ON/OFF, got: ${value}`);
}

/**
 * Parses multi-line public key from environment variable
 * Environment variables escape newlines as \n, so we need to convert them
 */
function parsePublicKey(name: string): string {
  const value = requireEnv(name);

  // Replace escaped \n with actual newlines
  return value.replace(/\\n/g, '\n');
}

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcSqlConfig | undefined;

export function loadConfig(): CwcSqlConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProd = runtimeEnvironment === 'prod';
    const isDev = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnit = runtimeEnvironment === 'unit';
    const isE2E = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcSqlConfig = {
      // Environment
      runtimeEnvironment,
      isProd,
      isDev,
      isTest,
      isUnit,
      isE2E,

      // Service
      servicePort: parseNumber('SERVICE_PORT', 5003),

      // Database connection
      databaseServer: requireEnv('DATABASE_SERVER'),
      databaseName: requireEnv('DATABASE_NAME'),
      databaseConnectTimeout: parseNumber('DATABASE_CONNECT_TIMEOUT'),
      databaseConnectionAcquireTimeout: parseNumber('DATABASE_CONNECTION_ACQUIRE_TIMEOUT'),
      databaseConnectionQueueLimit: parseNumber('DATABASE_CONNECTION_QUEUE_LIMIT'),
      databaseConnectionLimit: parseNumber('DATABASE_CONNECTION_LIMIT'),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),

      // Rate limiting
      // RATE_LIMITER_POINTS: Maximum number of requests allowed per duration
      // RATE_LIMITER_DURATION: Time window in seconds
      // Example: 100 points / 60 seconds = max 100 requests per minute per IP
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 100),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 60),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE'),
      logErrorsToDatabase: parseBoolean('LOG_ERRORS_TO_DATABASE'),

      // Query caching
      queryCacheEnabled: parseBoolean('QUERY_CACHE_ENABLED'),
      queryCacheTtl: parseNumber('QUERY_CACHE_TTL'),
      queryCacheMaxKeys: parseNumber('QUERY_CACHE_MAX_KEYS'),

      // End-to-end testing (optional, only in e2e environment)
      endToEndMockValues:
        isE2E && process.env['END_TO_END_TESTING_MOCK_VALUES']
          ? JSON.parse(process.env['END_TO_END_TESTING_MOCK_VALUES'])
          : undefined,

      // Secrets (nested)
      secrets: {
        databaseUser: requireEnv('DATABASE_USER'),
        databasePassword: requireEnv('DATABASE_PASSWORD'),
        sqlClientApiKey: parsePublicKey('SQL_CLIENT_API_KEY'),
      },
    };

    // Validate database connection settings
    if (config.databaseConnectTimeout <= 0) {
      throw new Error('DATABASE_CONNECT_TIMEOUT must be greater than 0');
    }
    if (config.databaseConnectionAcquireTimeout <= 0) {
      throw new Error('DATABASE_CONNECTION_ACQUIRE_TIMEOUT must be greater than 0');
    }
    if (config.databaseConnectionQueueLimit <= 0) {
      throw new Error('DATABASE_CONNECTION_QUEUE_LIMIT must be greater than 0');
    }
    if (config.databaseConnectionLimit <= 0) {
      throw new Error('DATABASE_CONNECTION_LIMIT must be greater than 0');
    }

    // Validate cache settings
    if (config.queryCacheEnabled) {
      if (config.queryCacheTtl <= 0) {
        throw new Error('QUERY_CACHE_TTL must be greater than 0');
      }
      if (config.queryCacheMaxKeys <= 0) {
        throw new Error('QUERY_CACHE_MAX_KEYS must be greater than 0');
      }
    }

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-sql] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  Database Server: ${config.databaseServer}`);
      console.log(`  Database Name: ${config.databaseName}`);
      console.log(`  Database User: [REDACTED]`);
      console.log(`  Database Password: [REDACTED]`);
      console.log(`  Database Connect Timeout: ${config.databaseConnectTimeout}ms`);
      console.log(`  Database Connection Acquire Timeout: ${config.databaseConnectionAcquireTimeout}ms`);
      console.log(`  Database Connection Queue Limit: ${config.databaseConnectionQueueLimit}`);
      console.log(`  Database Connection Limit: ${config.databaseConnectionLimit}`);
      console.log(`  SQL Client API Key: [REDACTED]`);
      console.log(`  Debug Mode: ${config.debugMode}`);
      console.log(`  Log Errors to Database: ${config.logErrorsToDatabase}`);
      console.log(`  Query Cache Enabled: ${config.queryCacheEnabled}`);
      if (config.queryCacheEnabled) {
        console.log(`  Query Cache TTL: ${config.queryCacheTtl} minutes`);
        console.log(`  Query Cache Max Keys: ${config.queryCacheMaxKeys}`);
      }
    }

    return config;
  } catch (error) {
    console.error('[cwc-sql] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

packages/cwc-sql/src/database/connection.ts

import mariadb from 'mariadb';
import type { CwcSqlConfig } from '../config';

/**
 * Global connection pool singleton
 */
let pool: mariadb.Pool | undefined;

/**
 * Creates and returns the MariaDB connection pool
 * Implements security best practices and connection management
 */
export function createPool(config: CwcSqlConfig): mariadb.Pool {
  if (pool) {
    return pool;
  }

  // Determine if running locally (use localhost without SSL)
  const isLocalHost =
    config.databaseServer === 'localhost' ||
    config.databaseServer === '127.0.0.1' ||
    config.databaseServer.startsWith('localhost:');

  // SSL configuration for production environments
  const useSSL = config.isProd && !isLocalHost;

  if (config.debugMode) {
    console.log('[cwc-sql] Creating MariaDB connection pool:');
    console.log(`  Host: ${config.databaseServer}`);
    console.log(`  Database: ${config.databaseName}`);
    console.log(`  User: [REDACTED]`);
    console.log(`  Connection Limit: ${config.databaseConnectionLimit}`);
    console.log(`  Acquire Timeout: ${config.databaseConnectionAcquireTimeout}ms`);
    console.log(`  Connect Timeout: ${config.databaseConnectTimeout}ms`);
    console.log(`  Queue Limit: ${config.databaseConnectionQueueLimit}`);
    console.log(`  SSL: ${useSSL ? 'enabled' : 'disabled'}`);
    console.log(`  Multiple Statements: false (security)`);
    console.log(`  Named Placeholders: true`);
  }

  const poolConfig = {
    // Connection details
    host: config.databaseServer,
    database: config.databaseName,
    user: config.secrets.databaseUser,
    password: config.secrets.databasePassword,

    // Connection pool settings
    connectionLimit: config.databaseConnectionLimit,
    acquireTimeout: config.databaseConnectionAcquireTimeout,
    connectTimeout: config.databaseConnectTimeout,

    // Security settings
    multipleStatements: false, // CRITICAL: Prevents SQL injection via multiple statements
    ...(useSSL && { ssl: { rejectUnauthorized: true } }),

    // Query settings
    namedPlaceholders: true, // Enable :paramName syntax for better readability
    dateStrings: true, // Return dates as strings to avoid timezone conversion issues
    timezone: 'UTC', // Use UTC for all date/time operations
    charset: 'utf8mb4', // Full Unicode support including emojis

    // Connection behavior
    idleTimeout: 60000, // Close idle connections after 60 seconds
    minimumIdle: 0, // Allow pool to shrink to 0 connections when idle
  };

  pool = mariadb.createPool(poolConfig);

  return pool;
}

/**
 * Gets the existing connection pool
 * Throws if pool hasn't been created yet
 */
export function getPool(): mariadb.Pool {
  if (!pool) {
    throw new Error('Database connection pool not initialized. Call createPool() first.');
  }
  return pool;
}

/**
 * Tests the database connection
 * Returns true if connection is successful, throws error otherwise
 */
export async function testConnection(config: CwcSqlConfig): Promise<boolean> {
  const testPool = createPool(config);

  try {
    const conn = await testPool.getConnection();

    try {
      // Test query to verify connection
      const result = await conn.query('SELECT 1 as test');

      if (config.debugMode) {
        console.log('[cwc-sql] Database connection test successful');
      }

      return result && result[0]?.test === 1;
    } finally {
      conn.release();
    }
  } catch (error) {
    console.error('[cwc-sql] Database connection test failed:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    throw error;
  }
}

/**
 * Closes the connection pool
 * Should be called during graceful shutdown
 */
export async function closePool(): Promise<void> {
  if (pool) {
    await pool.end();
    pool = undefined;
  }
}

packages/cwc-sql/src/index.ts

2 versions

Version 1

import {
  loadDotEnv,
  createExpressService,
  type ExpressApi,
  type BackendUtilsConfigBasic,
} from 'cwc-backend-utils';
import type { RuntimeEnvironment } from 'cwc-types';
import type { Request, Response } from 'express';
import type { CwcSqlConfig } from './config';
import { loadConfig } from './config';
import { createPool, testConnection, closePool } from './database';
import { createVerifyTokenMiddleware } from './auth';
import { QueryCache } from './cache';
import { createCommandHandler } from './handlers';
import { logErrorToDatabase } from './errorLogger';

/**
 * Converts CwcSqlConfig to BackendUtilsConfigBasic for createExpressService
 */
function createBackendUtilsConfig(sqlConfig: CwcSqlConfig): BackendUtilsConfigBasic {
  return {
    debugMode: sqlConfig.debugMode,
    isDev: sqlConfig.isDev,
    isTest: sqlConfig.isTest,
    isProd: sqlConfig.isProd,
    isUnit: sqlConfig.isUnit,
    isE2E: sqlConfig.isE2E,
    corsOrigin: sqlConfig.corsOrigin,
    servicePort: sqlConfig.servicePort,
    rateLimiterPoints: sqlConfig.rateLimiterPoints,
    rateLimiterDuration: sqlConfig.rateLimiterDuration,
    devCorsOrigin: sqlConfig.isDev ? sqlConfig.corsOrigin : '',
    endToEndMockValues: sqlConfig.endToEndMockValues,
  };
}

/**
 * Health check endpoint for load balancers and monitoring
 */
function healthHandler(_req: Request, res: Response): void {
  res.json({
    status: 'healthy',
    service: 'cwc-sql',
    timestamp: new Date().toISOString(),
  });
}

/**
 * Main entry point for the cwc-sql microservice
 */
async function main(): Promise<void> {
  try {
    console.log('[cwc-sql] Starting cwc-sql microservice...');

    // Load environment variables
    loadDotEnv({
      serviceName: 'cwc-sql',
      environment: (process.env['RUNTIME_ENVIRONMENT'] as RuntimeEnvironment) || 'dev',
      debug: process.env['DEBUG_MODE'] === 'ON',
    });

    // Load and validate configuration
    const config = loadConfig();

    console.log('[cwc-sql] Configuration loaded successfully');

    // Create database connection pool
    createPool(config);

    console.log('[cwc-sql] Database connection pool created');

    // Test database connection
    await testConnection(config);

    console.log('[cwc-sql] Database connection test successful');

    // Create query cache
    const cache = new QueryCache(config);

    console.log('[cwc-sql] Query cache initialized');

    // Create JWT verification middleware
    const verifyToken = createVerifyTokenMiddleware(config);

    // Create command handler
    const commandHandler = createCommandHandler(cache, config);

    // Define API routes
    const apis: ExpressApi[] = [
      {
        version: 1,
        path: '/health',
        handler: healthHandler,
      },
      {
        version: 1,
        path: '/data/v1/command',
        handler: commandHandler,
      },
    ];

    // Create Express service
    const service = createExpressService({
      config: createBackendUtilsConfig(config),
      serviceName: 'cwc-sql',
      apis,
      allowGet: false,
      allowPost: true,
      allowOptions: true,
      payloadLimit: undefined,
    });

    // Apply JWT verification middleware to all routes
    service.expressApp.use(verifyToken);

    // Start the service
    service.start(apis);

    // Listen on configured port
    service.httpServer.listen(config.servicePort, () => {
      console.log('');
      console.log('='.repeat(60));
      console.log(`[cwc-sql] Service started successfully`);
      console.log(`[cwc-sql] Environment: ${config.runtimeEnvironment}`);
      console.log(`[cwc-sql] Port: ${config.servicePort}`);
      console.log(`[cwc-sql] Database: ${config.databaseServer}/${config.databaseName}`);
      console.log(`[cwc-sql] Cache: ${config.queryCacheEnabled ? 'enabled' : 'disabled'}`);
      console.log(`[cwc-sql] Debug: ${config.debugMode ? 'enabled' : 'disabled'}`);
      console.log('='.repeat(60));
      console.log('');
    });

    // Handle graceful shutdown
    const shutdown = async (signal: string): Promise<void> => {
      console.log(`\n[cwc-sql] Received ${signal}, shutting down gracefully...`);

      try {
        // Close HTTP server
        await new Promise<void>((resolve, reject) => {
          service.httpServer.close((err) => {
            if (err) {
              reject(err);
            } else {
              resolve();
            }
          });
        });

        console.log('[cwc-sql] HTTP server closed');

        // Close database pool
        await closePool();

        console.log('[cwc-sql] Database pool closed');

        console.log('[cwc-sql] Shutdown complete');
        process.exit(0);
      } catch (error) {
        console.error('[cwc-sql] Error during shutdown:', error);
        process.exit(1);
      }
    };

    // Register shutdown handlers
    process.on('SIGTERM', () => shutdown('SIGTERM'));
    process.on('SIGINT', () => shutdown('SIGINT'));

    // Handle uncaught errors
    process.on('unhandledRejection', async (reason, promise) => {
      console.error('[cwc-sql] Unhandled Rejection at:', promise, 'reason:', reason);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        try {
          const error = reason instanceof Error ? reason : new Error(String(reason));
          await logErrorToDatabase(error, 'index.ts:unhandledRejection', undefined, config);
        } catch (logError) {
          console.error('[cwc-sql] Failed to log unhandled rejection to database:', logError);
        }
      }

      // Don't exit on unhandled rejection in production
      if (!config.isProduction) {
        process.exit(1);
      }
    });

    process.on('uncaughtException', async (error) => {
      console.error('[cwc-sql] Uncaught Exception:', error);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        try {
          await logErrorToDatabase(error, 'index.ts:uncaughtException', undefined, config);
        } catch (logError) {
          console.error('[cwc-sql] Failed to log uncaught exception to database:', logError);
        }
      }

      // Always exit on uncaught exception
      process.exit(1);
    });
  } catch (error) {
    console.error('[cwc-sql] Failed to start service:', error);
    process.exit(1);
  }
}

// Start the service
main();

Version 2 (latest)

import {
  loadDotEnv,
  createExpressService,
  type ExpressApi,
  type BackendUtilsConfigBasic,
} from 'cwc-backend-utils';
import type { RuntimeEnvironment } from 'cwc-types';
import type { Request, Response } from 'express';
import type { CwcSqlConfig } from './config';
import { loadConfig } from './config';
import { createPool, testConnection, closePool } from './database';
import { createVerifyTokenMiddleware } from './auth';
import { QueryCache } from './cache';
import { createCommandHandler } from './handlers';
import { logErrorToDatabase } from './errorLogger';

/**
 * Converts CwcSqlConfig to BackendUtilsConfigBasic for createExpressService
 */
function createBackendUtilsConfig(sqlConfig: CwcSqlConfig): BackendUtilsConfigBasic {
  return {
    debugMode: sqlConfig.debugMode,
    isDev: sqlConfig.isDev,
    isTest: sqlConfig.isTest,
    isProd: sqlConfig.isProd,
    isUnit: sqlConfig.isUnit,
    isE2E: sqlConfig.isE2E,
    corsOrigin: sqlConfig.corsOrigin,
    servicePort: sqlConfig.servicePort,
    rateLimiterPoints: sqlConfig.rateLimiterPoints,
    rateLimiterDuration: sqlConfig.rateLimiterDuration,
    devCorsOrigin: sqlConfig.isDev ? sqlConfig.corsOrigin : '',
    endToEndMockValues: sqlConfig.endToEndMockValues,
  };
}

/**
 * Health check endpoint for load balancers and monitoring
 */
function healthHandler(_req: Request, res: Response): void {
  res.json({
    status: 'healthy',
    service: 'cwc-sql',
    timestamp: new Date().toISOString(),
  });
}

/**
 * Main entry point for the cwc-sql microservice
 */
async function main(): Promise<void> {
  try {
    console.log('[cwc-sql] Starting cwc-sql microservice...');

    // Load environment variables
    loadDotEnv({
      serviceName: 'cwc-sql',
      environment: (process.env['RUNTIME_ENVIRONMENT'] as RuntimeEnvironment) || 'dev',
      debug: process.env['DEBUG_MODE'] === 'ON',
    });

    // Load and validate configuration
    const config = loadConfig();

    console.log('[cwc-sql] Configuration loaded successfully');

    // Create database connection pool
    createPool(config);

    console.log('[cwc-sql] Database connection pool created');

    // Test database connection
    await testConnection(config);

    console.log('[cwc-sql] Database connection test successful');

    // Create query cache
    const cache = new QueryCache(config);

    console.log('[cwc-sql] Query cache initialized');

    // Create JWT verification middleware
    const verifyToken = createVerifyTokenMiddleware(config);

    // Create command handler
    const commandHandler = createCommandHandler(cache, config);

    // Define API routes
    const apis: ExpressApi[] = [
      {
        version: 1,
        path: '/health',
        handler: healthHandler,
      },
      {
        version: 1,
        path: '/data/v1/command',
        handler: commandHandler,
      },
    ];

    // Create Express service
    const service = createExpressService({
      config: createBackendUtilsConfig(config),
      serviceName: 'cwc-sql',
      apis,
      allowGet: false,
      allowPost: true,
      allowOptions: true,
      payloadLimit: undefined,
    });

    // Apply JWT verification middleware to all routes
    service.expressApp.use(verifyToken);

    // Start the service
    service.start(apis);

    // Listen on configured port
    service.httpServer.listen(config.servicePort, () => {
      console.log('');
      console.log('='.repeat(60));
      console.log(`[cwc-sql] Service started successfully`);
      console.log(`[cwc-sql] Environment: ${config.runtimeEnvironment}`);
      console.log(`[cwc-sql] Port: ${config.servicePort}`);
      console.log(`[cwc-sql] Database: ${config.databaseServer}/${config.databaseName}`);
      console.log(`[cwc-sql] Cache: ${config.queryCacheEnabled ? 'enabled' : 'disabled'}`);
      console.log(`[cwc-sql] Debug: ${config.debugMode ? 'enabled' : 'disabled'}`);
      console.log('='.repeat(60));
      console.log('');
    });

    // Handle graceful shutdown
    const shutdown = async (signal: string): Promise<void> => {
      console.log(`\n[cwc-sql] Received ${signal}, shutting down gracefully...`);

      try {
        // Close HTTP server
        await new Promise<void>((resolve, reject) => {
          service.httpServer.close((err) => {
            if (err) {
              reject(err);
            } else {
              resolve();
            }
          });
        });

        console.log('[cwc-sql] HTTP server closed');

        // Close database pool
        await closePool();

        console.log('[cwc-sql] Database pool closed');

        console.log('[cwc-sql] Shutdown complete');
        process.exit(0);
      } catch (error) {
        console.error('[cwc-sql] Error during shutdown:', error);
        process.exit(1);
      }
    };

    // Register shutdown handlers
    process.on('SIGTERM', () => shutdown('SIGTERM'));
    process.on('SIGINT', () => shutdown('SIGINT'));

    // Handle uncaught errors
    process.on('unhandledRejection', async (reason, promise) => {
      console.error('[cwc-sql] Unhandled Rejection at:', promise, 'reason:', reason);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        try {
          const error = reason instanceof Error ? reason : new Error(String(reason));
          await logErrorToDatabase(error, 'index.ts:unhandledRejection', undefined, config);
        } catch (logError) {
          console.error('[cwc-sql] Failed to log unhandled rejection to database:', logError);
        }
      }

      // Don't exit on unhandled rejection in production
      if (!config.isProd) {
        process.exit(1);
      }
    });

    process.on('uncaughtException', async (error) => {
      console.error('[cwc-sql] Uncaught Exception:', error);

      // Log to database if enabled
      if (config.logErrorsToDatabase) {
        try {
          await logErrorToDatabase(error, 'index.ts:uncaughtException', undefined, config);
        } catch (logError) {
          console.error('[cwc-sql] Failed to log uncaught exception to database:', logError);
        }
      }

      // Always exit on uncaught exception
      process.exit(1);
    });
  } catch (error) {
    console.error('[cwc-sql] Failed to start service:', error);
    process.exit(1);
  }
}

// Start the service
main();

packages/cwc-storage/CLAUDE.md

cwc-storage Package

File storage microservice for CWC application. Provides filesystem-based storage for coding session data files organized by project.

Architecture

Standalone Microservice:

Does NOT use database (no SqlClient dependency)
Uses file-based Logger (writes to ./logs/{date}.log)
Authenticates via API key (x-api-key header)
Uses BackendUtilsConfigBasic (not full BackendUtilsConfig)

Storage Model:

Files organized by projectId directories
Path: {STORAGE_VOLUME_PATH}/{projectId}/{filename}
Validates filenames to prevent path traversal attacks

Directory Structure:

{STORAGE_VOLUME_PATH}/
├── {projectId}/                                           # Project natural key/slug
│   ├── 2025-11-19_17-16-35_abc123-def456.json.gz         # {timestamp}_{sessionId}.json.gz
│   ├── 2025-11-20_09-30-00_xyz789-uvw012.json.gz
│   └── ...
├── another-project/
│   └── ...

Configuration Pattern

Follows cwc-sql pattern:

Config in src/config/ folder with 3 files:
- config.types.ts - CwcStorageConfig type definition
- loadConfig.ts - Loads and validates from environment
- index.ts - Exports
Uses shared helpers from cwc-backend-utils:
- requireEnv(), optionalEnv(), parseNumber(), parseBoolean(), parseJson()
Adapter function converts to BackendUtilsConfigBasic for Express service

Required Environment Variables:

RUNTIME_ENVIRONMENT=dev  # dev | test | prod | unit | e2e
SERVICE_PORT=5030
CORS_ORIGIN=http://localhost:3000
STORAGE_API_KEY=your-secret-api-key
RATE_LIMITER_POINTS=15
RATE_LIMITER_DURATION=1
STORAGE_VOLUME_PATH=/path/to/storage
STORAGE_LOG_PATH=./logs
DEBUG_MODE=ON  # ON | OFF
DEV_CORS_ORIGIN=

API Routes

All routes require x-api-key header and use POST method.

Route	Description	Payload
`/storage/v1/coding-session-data-get`	Retrieve session file	`{ projectId, filename }`
`/storage/v1/coding-session-data-put`	Store session file	`{ projectId, filename, dataUri }`
`/storage/v1/coding-session-data-delete`	Delete session file	`{ projectId, filename }`

Example Usage:

// PUT a session-data file
{
  projectId: "coding-with-claude",
  filename: "2025-11-19_17-16-35_abc123-def456.json.gz",
  dataUri: "<base64-encoded-gzipped-json>"
}

// GET a session-data file
{
  projectId: "coding-with-claude",
  filename: "2025-11-19_17-16-35_abc123-def456.json.gz"
}

Security

API Key Authentication:

Uses constant-time comparison (crypto.timingSafeEqual) to prevent timing attacks
API key required in x-api-key header for all requests

HTTPS Enforcement:

Only required in production (isProd: true)
Checks x-forwarded-proto header for proxy/load balancer scenarios

Filename Validation:

Rejects filenames with /, \, or ..
Prevents path traversal attacks

File-Based Logger

Different from cwc-backend-utils Logger:

Writes to filesystem ({storageLogPath}/{YYYY-MM-DD}.log)
Does NOT write to database (cwc-storage has no DB access)
Supports ERROR, INFO, DEBUG levels
DEBUG only outputs when debugMode: true

Dependency Injection Pattern

Config passed to constructors (not imported globally):

// index.ts
const config = loadConfig();
const apis: ExpressApi[] = [new StorageApiV1(config)];

// StorageApiV1 passes config to handlers
const handlerFactories = {
  storage: () => new StorageHandler(handlerOptions, this.config),
};

// Routes receive config for storage functions
export const getRoutes = (config: CwcStorageConfig): StorageRouteConfigs => ({
  '/coding-session-data-get': {
    worker: createGetFromStorage(config),
    // ...
  },
});

Related Packages

Depends On:

cwc-backend-utils (workspace) - Express service factory, config helpers, loadDotEnv
cwc-types (workspace) - RuntimeEnvironment type
express - Web framework

Does NOT Depend On:

cwc-sql - No database access
SqlClient - No database queries

packages/cwc-storage/src/apis/StorageApiV1/index.ts

import crypto from 'crypto';
import { NextFunction, Request, Response } from 'express';
import { RequestPayload, StorageApi } from '../../types';
import { getRoutes } from './routes';
import {
  StorageApiResponseData,
  StorageHandlerResponse,
  StorageRouteConfigs,
  StorageRouteHandler,
  StorageRouteHandlerOptions,
} from './types';
import { StorageHandler } from './StorageHandler';
import { Logger } from '../../Logger';
import type { CwcStorageConfig } from '../../config';

const codeLocation = 'src/apis/StorageApiV1/index.ts';

export class StorageApiV1 implements StorageApi {
  private routes: StorageRouteConfigs;
  private logger: Logger;
  private apiKey: string;
  private config: CwcStorageConfig;

  constructor(config: CwcStorageConfig) {
    this.config = config;
    this.logger = new Logger({
      logPath: config.storageLogPath,
      serviceName: 'cwc-storage',
      debugMode: config.debugMode,
    });
    this.routes = getRoutes(config);
    this.apiKey = config.secrets.storageApiKey;
  }

  public get path(): string {
    return '/storage/v1';
  }

  public get version(): number {
    return 1;
  }

  private validateApiKey(req: Request): boolean {
    // Check for API key in x-api-key header
    const requestApiKey = req.headers['x-api-key'];

    if (!requestApiKey || typeof requestApiKey !== 'string') {
      return false;
    }

    if (!this.apiKey) {
      this.logger.logError({
        username: undefined,
        codeLocation,
        message: 'API key not configured',
        error: 'storageApiKey is undefined',
        value: undefined,
        request: undefined,
      });
      return false;
    }

    // Use constant-time comparison to prevent timing attacks
    try {
      const requestBuffer = Buffer.from(requestApiKey);
      const apiKeyBuffer = Buffer.from(this.apiKey);

      // timingSafeEqual requires equal-length buffers
      if (requestBuffer.length !== apiKeyBuffer.length) {
        return false;
      }

      return crypto.timingSafeEqual(requestBuffer, apiKeyBuffer);
    } catch (error) {
      this.logger.logError({
        username: undefined,
        codeLocation,
        message: 'API key comparison failed',
        error,
        value: undefined,
        request: undefined,
      });
      return false;
    }
  }

  private isHttpsRequired(): boolean {
    // Only require HTTPS in "prod" environment
    return this.config.isProd;
  }

  private validateHttps(req: Request): boolean {
    // Check if HTTPS is required
    if (!this.isHttpsRequired()) {
      return true; // Allow HTTP in development/test
    }

    // Check protocol from request
    const protocol = req.protocol;
    const isSecure = req.secure || protocol === 'https';

    // Also check x-forwarded-proto header (for proxies/load balancers)
    const forwardedProto = req.headers['x-forwarded-proto'];
    const isForwardedSecure = forwardedProto === 'https';

    return isSecure || isForwardedSecure;
  }

  public async handler(req: Request, res: Response, next: NextFunction): Promise<void> {
    const logError = (message: string, error: unknown, value: unknown = undefined): void => {
      this.logger.logError({
        username: undefined,
        request: undefined,
        codeLocation,
        message,
        value,
        error,
      });
    };

    try {
      if (res.statusCode !== 200) {
        return;
      }
      if (res.writableEnded) {
        return;
      }

      const { body, path, query, method } = req;

      // Enforce HTTPS in "prod"
      if (!this.validateHttps(req)) {
        logError('HTTPS required', 'Non-HTTPS request in "prod" environment');
        res.status(403).send('HTTPS required');
        return;
      }

      // Validate API key for all requests
      if (!this.validateApiKey(req)) {
        res.status(401).send('unauthorized');
        return;
      }

      // Validate the path
      if (!this.isPathValid(path)) {
        res.status(404).send('not found');
        return;
      }

      // Locate the corresponding route config object
      const routeConfig = this.routes[path];
      if (!routeConfig) {
        logError('handler', 'ROUTE CONFIG NOT FOUND', { path });
        next();
        return;
      }

      if (method !== routeConfig.method) {
        logError('handler', 'ROUTE NOT FOUND', { path });
        res.status(404).send('invalid route');
        return;
      }

      // Build payload from body and query params
      const payload: RequestPayload = body ?? {};
      if (routeConfig.params && routeConfig.params.length > 0 && query) {
        for (let i = 0; i < routeConfig.params.length; i++) {
          const key = routeConfig.params[i];
          if (key) {
            payload[key] = query[key.toLowerCase()];
          }
        }
      }

      // Instantiate the route handler
      const handlerOptions: StorageRouteHandlerOptions = {
        payload,
        routeConfig,
      };

      const handlerFactories = {
        storage: () => new StorageHandler(handlerOptions, this.config),
      };
      type FactoryFunction = () => StorageRouteHandler;
      const factory: FactoryFunction = handlerFactories[routeConfig.handlerType];

      if (!factory) {
        logError('handler', 'HANDLER FACTORY NOT FOUND', { path });
        res.status(404).send('invalid route');
        return;
      }

      const routeHandler: StorageRouteHandler = factory();
      if (!routeHandler) {
        logError('handler', 'HANDLER FACTORY FAILED', { path });
        res.status(404).send('invalid route');
        return;
      }

      // Invoke the route handler
      const handlerResponse: StorageHandlerResponse = await routeHandler.processRequest();

      const statusCode = handlerResponse.statusCode;
      const data: StorageApiResponseData = {
        success: false,
        data: undefined,
      };

      const success = statusCode === 200 && handlerResponse?.success === true;
      if (success === true) {
        data.success = true;
        data.data = handlerResponse.data;
      }

      if (routeConfig.cacheControl) {
        res.header('Cache-Control', routeConfig.cacheControl);
      }

      res.status(statusCode).json(data);
    } catch (error) {
      logError('StorageApiV1.handler - ERROR', error);
      res.status(404).send('request failed');
    }
  }

  private isPathValid(path: string): boolean {
    if (!path || path === '/') {
      return false;
    }
    return true;
  }
}

packages/cwc-storage/src/config/config.types.ts

2 versions

Version 1

import type { RuntimeEnvironment } from 'cwc-types';

/**
 * Secret configuration values for cwc-storage
 * These values must be provided via secrets file, never committed to code
 */
export type CwcStorageConfigSecrets = {
  storageApiKey: string;
};

/**
 * Configuration for the cwc-storage microservice
 */
export type CwcStorageConfig = {
  // Environment
  runtimeEnvironment: RuntimeEnvironment;
  isProd: boolean;
  isDev: boolean;
  isTest: boolean;
  isUnit: boolean;
  isE2E: boolean;

  // Service
  servicePort: number;

  // Security
  corsOrigin: string;

  // Rate limiting
  rateLimiterPoints: number;
  rateLimiterDuration: number;

  // Development settings
  devCorsOrigin: string;

  // Debugging
  debugMode: boolean;

  // Storage-specific settings
  storageVolumePath: string;
  storageLogPath: string;

  // Secrets (nested)
  secrets: CwcStorageConfigSecrets;
};

Version 2 (latest)

import type { RuntimeEnvironment } from 'cwc-types';

/**
 * Secret configuration values for cwc-storage
 * These values must be provided via secrets file, never committed to code
 */
export type CwcStorageConfigSecrets = {
  storageApiKey: string;
};

/**
 * Configuration for the cwc-storage microservice
 */
export type CwcStorageConfig = {
  // Environment
  runtimeEnvironment: RuntimeEnvironment;
  isProd: boolean;
  isDev: boolean;
  isTest: boolean;
  isUnit: boolean;
  isE2E: boolean;

  // Service
  servicePort: number;

  // Security
  corsOrigin: string;

  // Rate limiting
  rateLimiterPoints: number;
  rateLimiterDuration: number;

  // dev settings
  devCorsOrigin: string;

  // Debugging
  debugMode: boolean;

  // Storage-specific settings
  storageVolumePath: string;
  storageLogPath: string;

  // Secrets (nested)
  secrets: CwcStorageConfigSecrets;
};

packages/cwc-storage/src/config/loadConfig.ts

2 versions

Version 1

import type { RuntimeEnvironment } from 'cwc-types';
import { requireEnv, optionalEnv, parseNumber, parseBoolean } from 'cwc-backend-utils';
import type { CwcStorageConfig } from './config.types';

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcStorageConfig | undefined;

export function loadConfig(): CwcStorageConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProd = runtimeEnvironment === 'prod';
    const isDev = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnit = runtimeEnvironment === 'unit';
    const isE2E = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcStorageConfig = {
      // Environment
      runtimeEnvironment,
      isProd,
      isDev,
      isTest,
      isUnit,
      isE2E,

      // Service
      servicePort: parseNumber('SERVICE_PORT', 5004),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),

      // Rate limiting
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 15),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 1),

      // Development settings
      devCorsOrigin: optionalEnv('DEV_CORS_ORIGIN', 'http://localhost:3000'),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE', false),

      // Storage-specific settings
      storageVolumePath: requireEnv('STORAGE_VOLUME_PATH'),
      storageLogPath: optionalEnv('STORAGE_LOG_PATH', './logs'),

      // Secrets (nested)
      secrets: {
        storageApiKey: requireEnv('STORAGE_API_KEY'),
      },
    };

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Validate storage volume path is not empty
    if (config.storageVolumePath.trim() === '') {
      throw new Error('STORAGE_VOLUME_PATH cannot be empty');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-storage] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  CORS Origin: ${config.corsOrigin}`);
      console.log(`  Storage API Key: [REDACTED]`);
      console.log(
        `  Rate Limiter: ${config.rateLimiterPoints} points / ${config.rateLimiterDuration}s`
      );
      console.log(`  Storage Volume Path: ${config.storageVolumePath}`);
      console.log(`  Storage Log Path: ${config.storageLogPath}`);
      console.log(`  Debug Mode: ${config.debugMode}`);
    }

    return config;
  } catch (error) {
    console.error('[cwc-storage] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

Version 2 (latest)

import type { RuntimeEnvironment } from 'cwc-types';
import { requireEnv, optionalEnv, parseNumber, parseBoolean } from 'cwc-backend-utils';
import type { CwcStorageConfig } from './config.types';

/**
 * Validates runtime environment value
 */
function validateRuntimeEnvironment(value: string): RuntimeEnvironment {
  const validEnvironments = ['dev', 'test', 'prod', 'unit', 'e2e'];
  if (!validEnvironments.includes(value)) {
    throw new Error(
      `Invalid RUNTIME_ENVIRONMENT: ${value}. Must be one of: ${validEnvironments.join(', ')}`
    );
  }
  return value as RuntimeEnvironment;
}

/**
 * Loads and validates configuration from environment variables
 * Caches the configuration on first load
 */
let cachedConfig: CwcStorageConfig | undefined;

export function loadConfig(): CwcStorageConfig {
  // Return cached config if already loaded
  if (cachedConfig) {
    return cachedConfig;
  }

  try {
    // Parse runtime environment
    const runtimeEnvironment = validateRuntimeEnvironment(requireEnv('RUNTIME_ENVIRONMENT'));

    // Derive environment booleans
    const isProd = runtimeEnvironment === 'prod';
    const isDev = runtimeEnvironment === 'dev';
    const isTest = runtimeEnvironment === 'test';
    const isUnit = runtimeEnvironment === 'unit';
    const isE2E = runtimeEnvironment === 'e2e';

    // Parse configuration
    const config: CwcStorageConfig = {
      // Environment
      runtimeEnvironment,
      isProd,
      isDev,
      isTest,
      isUnit,
      isE2E,

      // Service
      servicePort: parseNumber('SERVICE_PORT', 5004),

      // Security
      corsOrigin: requireEnv('CORS_ORIGIN'),

      // Rate limiting
      rateLimiterPoints: parseNumber('RATE_LIMITER_POINTS', 15),
      rateLimiterDuration: parseNumber('RATE_LIMITER_DURATION', 1),

      // dev settings
      devCorsOrigin: optionalEnv('DEV_CORS_ORIGIN', 'http://localhost:3000'),

      // Debugging
      debugMode: parseBoolean('DEBUG_MODE', false),

      // Storage-specific settings
      storageVolumePath: requireEnv('STORAGE_VOLUME_PATH'),
      storageLogPath: optionalEnv('STORAGE_LOG_PATH', './logs'),

      // Secrets (nested)
      secrets: {
        storageApiKey: requireEnv('STORAGE_API_KEY'),
      },
    };

    // Validate port
    if (config.servicePort < 1 || config.servicePort > 65535) {
      throw new Error('SERVICE_PORT must be between 1 and 65535');
    }

    // Validate storage volume path is not empty
    if (config.storageVolumePath.trim() === '') {
      throw new Error('STORAGE_VOLUME_PATH cannot be empty');
    }

    // Cache the configuration
    cachedConfig = config;

    // Log configuration in debug mode (redact sensitive data)
    if (config.debugMode) {
      console.log('[cwc-storage] Configuration loaded:');
      console.log(`  Environment: ${config.runtimeEnvironment}`);
      console.log(`  Service Port: ${config.servicePort}`);
      console.log(`  CORS Origin: ${config.corsOrigin}`);
      console.log(`  Storage API Key: [REDACTED]`);
      console.log(
        `  Rate Limiter: ${config.rateLimiterPoints} points / ${config.rateLimiterDuration}s`
      );
      console.log(`  Storage Volume Path: ${config.storageVolumePath}`);
      console.log(`  Storage Log Path: ${config.storageLogPath}`);
      console.log(`  Debug Mode: ${config.debugMode}`);
    }

    return config;
  } catch (error) {
    console.error('[cwc-storage] Failed to load configuration:');
    if (error instanceof Error) {
      console.error(`  ${error.message}`);
    } else {
      console.error(error);
    }
    console.error('\nPlease check your environment variables and try again.');
    process.exit(1);
  }
}

packages/cwc-storage/src/index.ts

2 versions

Version 1

import {
  loadDotEnv,
  createExpressService,
  type ExpressApi,
  type BackendUtilsConfigBasic,
} from 'cwc-backend-utils';
import type { RuntimeEnvironment } from 'cwc-types';
import type { CwcStorageConfig } from './config';
import { loadConfig } from './config';
import { StorageApiV1 } from './apis/StorageApiV1';

console.log(`
 .d8888b. 88888888888 .d88888b.  8888888b.         d8888  .d8888b.  8888888888
d88P  Y88b    888    d88P" "Y88b 888   Y88b       d88888 d88P  Y88b 888
Y88b.         888    888     888 888    888      d88P888 888    888 888
 "Y888b.      888    888     888 888   d88P     d88P 888 888        8888888
    "Y88b.    888    888     888 8888888P"     d88P  888 888  88888 888
      "888    888    888     888 888 T88b     d88P   888 888    888 888
Y88b  d88P    888    Y88b. .d88P 888  T88b   d8888888888 Y88b  d88P 888
 "Y8888P"     888     "Y88888P"  888   T88b d88P     888  "Y8888P88 8888888888
`);

/**
 * Converts CwcStorageConfig to BackendUtilsConfigBasic for createExpressService
 */
function createBackendUtilsConfig(storageConfig: CwcStorageConfig): BackendUtilsConfigBasic {
  return {
    debugMode: storageConfig.debugMode,
    isDev: storageConfig.isDev,
    isTest: storageConfig.isTest,
    isProd: storageConfig.isProd,
    isUnit: storageConfig.isUnit,
    isE2E: storageConfig.isE2E,
    corsOrigin: storageConfig.corsOrigin,
    servicePort: storageConfig.servicePort,
    rateLimiterPoints: storageConfig.rateLimiterPoints,
    rateLimiterDuration: storageConfig.rateLimiterDuration,
    devCorsOrigin: storageConfig.devCorsOrigin,
  };
}

/**
 * Main entry point for the cwc-storage microservice
 */
async function main(): Promise<void> {
  try {
    console.log('[cwc-storage] Starting cwc-storage microservice...');

    // Load environment variables
    loadDotEnv({
      serviceName: 'cwc-storage',
      environment: (process.env['RUNTIME_ENVIRONMENT'] as RuntimeEnvironment) || 'dev',
      debug: process.env['DEBUG_MODE'] === 'ON',
    });

    // Load and validate configuration
    const config = loadConfig();

    console.log('[cwc-storage] Configuration loaded successfully');

    // Create API instances
    const apis: ExpressApi[] = [new StorageApiV1(config)];

    // Create Express service
    const service = createExpressService({
      config: createBackendUtilsConfig(config),
      serviceName: 'cwc-storage',
      apis,
      allowGet: false,
      allowOptions: true,
      allowPost: true,
      payloadLimit: '2mb',
    });

    // Start the service
    service.start(apis);

    console.log('');
    console.log('='.repeat(60));
    console.log(`[cwc-storage] Service started successfully`);
    console.log(`[cwc-storage] Environment: ${config.runtimeEnvironment}`);
    console.log(`[cwc-storage] Port: ${config.servicePort}`);
    console.log(`[cwc-storage] Storage Volume: ${config.storageVolumePath}`);
    console.log(`[cwc-storage] Debug: ${config.debugMode ? 'enabled' : 'disabled'}`);
    console.log('='.repeat(60));
    console.log('');

    // Handle graceful shutdown
    const shutdown = async (signal: string): Promise<void> => {
      console.log(`\n[cwc-storage] Received ${signal}, shutting down gracefully...`);

      try {
        // Close HTTP server
        await new Promise<void>((resolve, reject) => {
          service.httpServer.close((err) => {
            if (err) {
              reject(err);
            } else {
              resolve();
            }
          });
        });

        console.log('[cwc-storage] HTTP server closed');
        console.log('[cwc-storage] Shutdown complete');
        process.exit(0);
      } catch (error) {
        console.error('[cwc-storage] Error during shutdown:', error);
        process.exit(1);
      }
    };

    // Register shutdown handlers
    process.on('SIGTERM', () => shutdown('SIGTERM'));
    process.on('SIGINT', () => shutdown('SIGINT'));

    // Handle uncaught errors
    process.on('unhandledRejection', (reason, promise) => {
      console.error('[cwc-storage] Unhandled Rejection at:', promise, 'reason:', reason);

      // Don't exit on unhandled rejection in production
      if (!config.isProduction) {
        process.exit(1);
      }
    });

    process.on('uncaughtException', (error) => {
      console.error('[cwc-storage] Uncaught Exception:', error);

      // Always exit on uncaught exception
      process.exit(1);
    });
  } catch (error) {
    console.error('[cwc-storage] Failed to start service:', error);
    process.exit(1);
  }
}

// Start the service
main();

// Export for testing
export { main };

Version 2 (latest)

import {
  loadDotEnv,
  createExpressService,
  type ExpressApi,
  type BackendUtilsConfigBasic,
} from 'cwc-backend-utils';
import type { RuntimeEnvironment } from 'cwc-types';
import type { CwcStorageConfig } from './config';
import { loadConfig } from './config';
import { StorageApiV1 } from './apis/StorageApiV1';

console.log(`
 .d8888b. 88888888888 .d88888b.  8888888b.         d8888  .d8888b.  8888888888
d88P  Y88b    888    d88P" "Y88b 888   Y88b       d88888 d88P  Y88b 888
Y88b.         888    888     888 888    888      d88P888 888    888 888
 "Y888b.      888    888     888 888   d88P     d88P 888 888        8888888
    "Y88b.    888    888     888 8888888P"     d88P  888 888  88888 888
      "888    888    888     888 888 T88b     d88P   888 888    888 888
Y88b  d88P    888    Y88b. .d88P 888  T88b   d8888888888 Y88b  d88P 888
 "Y8888P"     888     "Y88888P"  888   T88b d88P     888  "Y8888P88 8888888888
`);

/**
 * Converts CwcStorageConfig to BackendUtilsConfigBasic for createExpressService
 */
function createBackendUtilsConfig(storageConfig: CwcStorageConfig): BackendUtilsConfigBasic {
  return {
    debugMode: storageConfig.debugMode,
    isDev: storageConfig.isDev,
    isTest: storageConfig.isTest,
    isProd: storageConfig.isProd,
    isUnit: storageConfig.isUnit,
    isE2E: storageConfig.isE2E,
    corsOrigin: storageConfig.corsOrigin,
    servicePort: storageConfig.servicePort,
    rateLimiterPoints: storageConfig.rateLimiterPoints,
    rateLimiterDuration: storageConfig.rateLimiterDuration,
    devCorsOrigin: storageConfig.devCorsOrigin,
  };
}

/**
 * Main entry point for the cwc-storage microservice
 */
async function main(): Promise<void> {
  try {
    console.log('[cwc-storage] Starting cwc-storage microservice...');

    // Load environment variables
    loadDotEnv({
      serviceName: 'cwc-storage',
      environment: (process.env['RUNTIME_ENVIRONMENT'] as RuntimeEnvironment) || 'dev',
      debug: process.env['DEBUG_MODE'] === 'ON',
    });

    // Load and validate configuration
    const config = loadConfig();

    console.log('[cwc-storage] Configuration loaded successfully');

    // Create API instances
    const apis: ExpressApi[] = [new StorageApiV1(config)];

    // Create Express service
    const service = createExpressService({
      config: createBackendUtilsConfig(config),
      serviceName: 'cwc-storage',
      apis,
      allowGet: false,
      allowOptions: true,
      allowPost: true,
      payloadLimit: '2mb',
    });

    // Start the service
    service.start(apis);

    console.log('');
    console.log('='.repeat(60));
    console.log(`[cwc-storage] Service started successfully`);
    console.log(`[cwc-storage] Environment: ${config.runtimeEnvironment}`);
    console.log(`[cwc-storage] Port: ${config.servicePort}`);
    console.log(`[cwc-storage] Storage Volume: ${config.storageVolumePath}`);
    console.log(`[cwc-storage] Debug: ${config.debugMode ? 'enabled' : 'disabled'}`);
    console.log('='.repeat(60));
    console.log('');

    // Handle graceful shutdown
    const shutdown = async (signal: string): Promise<void> => {
      console.log(`\n[cwc-storage] Received ${signal}, shutting down gracefully...`);

      try {
        // Close HTTP server
        await new Promise<void>((resolve, reject) => {
          service.httpServer.close((err) => {
            if (err) {
              reject(err);
            } else {
              resolve();
            }
          });
        });

        console.log('[cwc-storage] HTTP server closed');
        console.log('[cwc-storage] Shutdown complete');
        process.exit(0);
      } catch (error) {
        console.error('[cwc-storage] Error during shutdown:', error);
        process.exit(1);
      }
    };

    // Register shutdown handlers
    process.on('SIGTERM', () => shutdown('SIGTERM'));
    process.on('SIGINT', () => shutdown('SIGINT'));

    // Handle uncaught errors
    process.on('unhandledRejection', (reason, promise) => {
      console.error('[cwc-storage] Unhandled Rejection at:', promise, 'reason:', reason);

      // Don't exit on unhandled rejection in production
      if (!config.isProd) {
        process.exit(1);
      }
    });

    process.on('uncaughtException', (error) => {
      console.error('[cwc-storage] Uncaught Exception:', error);

      // Always exit on uncaught exception
      process.exit(1);
    });
  } catch (error) {
    console.error('[cwc-storage] Failed to start service:', error);
    process.exit(1);
  }
}

// Start the service
main();

// Export for testing
export { main };

Session 22: rename config env flags

Session 22: rename config env flags

Plan: Rename Environment Config Flags

Objective

Packages Affected

Implementation Steps

Step 1: Update Type Definitions (5 files)

Step 2: Update loadConfig Functions (4 files)

Step 3: Update Usage Sites

Step 4: Update Configuration Helper

Step 5: Update Test Files

Step 6: Update CLAUDE.md Documentation

Verification

Notes

Plan: Consolidate cwc-secrets Path References

Objective

Problem Found

Solution

Files to Modify

Step 1: Create localSecretsPaths.ts

Step 2: Update loadDotEnv.ts

Step 3: Update SqlClientKeysUtil.ts

Step 4: Update index.ts

Step 5: Update CLAUDE.md

Verification

Notes

Plan: Consolidate cwc-secrets Path References

Objective

Problem Found

Solution

Files to Modify

Step 1: Create localSecretsPaths.ts

Step 2: Update loadDotEnv.ts

Step 3: Update SqlClientKeysUtil.ts

Step 4: Update index.ts

Step 5: Update CLAUDE.md

Verification

Notes

Session 22: rename config env flags

CLAUDE.md

CRITICAL: Role and Professional Standards

Required Due Diligence for Every Task

Cross-Package Feature Planning

Package-Specific Documentation

Project Overview

What is codingwithclaude?

Project name & aliases

Proactive Documentation Philosophy

CLAUDE.md File Specification

Documentation Organization in Monorepos

File Access Restrictions and Security Boundaries

Workspace Boundaries

Prohibited File Access

Git Workflow

Architecture Overview

Monorepo Structure (future plan)

Development Tooling & Infrastructure

Monorepo Management

Node.js Version

Code Quality Tools

Root Scripts

Development Workflow

Package Creation Conventions

Key Architectural Decisions & Patterns

MariaDB Database

TypeScript

Path Construction (Searchability)

Naming Conventions for Configuration Values

Secret and API Key Generation

Cloud-Agnostic Microservices

Environment Configuration

Development Process

Tool, Framework, Version selection

Adopt a "roll-your-own" mentality

Code Review Workflow Patterns

Developer Should Continue Providing Comprehensive Feedback Lists

Recognize Step-by-Step Request Signals

Step-by-Step Review Pattern (Default for Code Reviews)

Alternative: Full Analysis First Pattern

Benefits of Step-by-Step Pattern

Step 1: Create `localSecretsPaths.ts`

Step 2: Update `loadDotEnv.ts`

Step 3: Update `SqlClientKeysUtil.ts`

Step 4: Update `index.ts`

Step 1: Create `localSecretsPaths.ts`

Step 2: Update `loadDotEnv.ts`

Step 3: Update `SqlClientKeysUtil.ts`

Step 4: Update `index.ts`