Developer MessagesClaude MessagesShow Tool Use

jeff

CwcUser vs CwcLogin: Architectural Analysis

After reviewing the cwc-auth code, and in preparation for the development work on cwc-api and cwc-website, I have some ideas that I will present below.
I am open to feedback and suggestions that will improve the quality and clarity of the code and the overall user and developer experience.
Please let me know if I have missed something in the cwc-auth code or misunderstood the implementation related to these topics.

Terminology

Terminology can be confusing, so I find it helpful to define some terms in the scope of the Cwc application.
In the Cwc app we will use the following terminology:

logon: the act of signing on to the site (authenticating), aka: log on, logging on
login: the artifact, claim stored in the JWT, produced by the authentication process, aka: CwcLogin
logout: the act of signing off of the site, aka: log off, logging off
isLoggedOn or isLoggedOff: whether or not the user is authenticated

In Cwc, we currently have UserJwtPayload:

export type UserJwtPayload = {
  // Standard JWT claims
  jti: string; // JWT ID - userJwtId (UUID) references userJwt table
  sub: number; // Subject - userPkId
  iat: number; // Issued at (Unix timestamp)
  exp: number; // Expiration (Unix timestamp)

  // Custom claims
  username: string;
  kulo: boolean; // Keep-user-logged-on flag
  ownedProjects: string[]; // Array of projectId (natural keys) user owns
};

The proposed types:

export type UserJwtPayload = {
  // Standard JWT claims
  jti: string; // JWT ID - userJwtId (UUID) references userJwt table
  sub: number; // Subject - userPkId
  iat: number; // Issued at (Unix timestamp)
  exp: number; // Expiration (Unix timestamp)

  // Custom claims
  login: CwcLogin;
};

export type CwcLogin = {
  autoLogonAttempted: boolean;
  username: string;
  deviceId: string;
  userJwtId: string;
  authToken: string;
  enabled?: boolean;
  loginType: CwcLoginType;
  username: string;
  kulo: boolean; // Keep-user-logged-on flag
  ownedProjects: string[]; // Array of projectId (natural keys) user owns
  isGuestUser: boolean;
};

export type CwcLoginType = 'cwc';

export type CwcUser = {
  userPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  username: string;
  loginType: CwcLoginType;
  loginDate: string;
  password?: string; // Optional: NULL for OAuth users
  email: string;
  emailConfirmed: boolean;
  deviceId: string;
  otpSecret?: string; // Optional: only present if 2FA enabled
  otpValidated: boolean;
  isGuestUser: boolean;
};

Why do we include isGuestUser?
The isGuestUser property is needed as a result of the frontend application's requirement that a user object is always present, even when the user has not yet logged on or has successfully logged off.
The website offers some features and views for guest users - readers of the site that have not yet signed up or have not signed in.
Always having a user object available simplifies the code (logic and types):

whether or not a user is logged on, a user object is created and cached
functions and components don't have to handle a null or undefined user object/parameter

The two types, CwcUser and CwcLogin, represent fundamentally different concepts despite both relating to "a user":

CwcUser — The persistent account record stored in the database

CwcLogin — The active session state embedded in a JWT token

Why Two Types Exist

Different Lifecycles

CwcUser exists from account creation until account deletion — it's the permanent record of who this person is
CwcLogin exists only for the duration of a session — it's a snapshot of the user's state at logon time

Different Data Ownership

CwcUser contains account data:

Credentials (password hash, OTP secret, PIN)
Profile information (email, phone, name)
Account status (enabled, email confirmed, phone confirmed)
Security tokens (password reset codes)

CwcLogin contains session data:

The JWT token itself
Pre-computed project ownership
Authorization context needed for access decisions

Security Boundary

This separation creates a critical security boundary:

Sensitive data stays in the database — Password hashes and OTP secrets never leave the user table
Session data travels in the JWT — Only non-sensitive, authorization-relevant data is embedded in tokens
If a JWT is compromised, the attacker gains session context but not credentials

Performance Optimization

The CwcLogin design embeds derived data that would otherwise require database queries on every request:

Which projects does this user own?

By computing these relationships at logon and caching them in the JWT, the system avoids repeated database joins for authorization checks. Access policy decisions become simple array lookups rather than queries.

How They Work Together

During authentication:

User provides credentials
cwc-auth validates against CwcUser record (password hash comparison)
cwc-auth queries projects, and other relationships
cwc-auth assembles a CwcLogin object with all derived data
CwcLogin is embedded in the JWT payload and returned to the client

During subsequent requests:

Client sends JWT with request
cwc-api extracts CwcLogin from JWT payload (no database query)
Access policies use CwcLogin for authorization decisions
If the actual CwcUser record is needed (account updates, GDPR export), it's queried separately

Trade-off Awareness

This design accepts a trade-off: session data can become stale.
When a user's data is changed after logon, such as creating a new project, their JWT's login.ownedProjects array won't reflect it until they re-authenticate (renew-session).
The system accepts this latency in exchange for the performance benefit of avoiding per-request membership queries.

This pattern is an example of separating identity (who you are) from authorization context (what you can do right now), optimized for a stateless API architecture.

Claude

I've read through your architectural analysis carefully. This is well-reasoned and demonstrates solid understanding of the separation of concerns between identity and session state. Let me provide feedback on a few areas.

Observations and Questions

1. Duplicate `username` in CwcLogin

Your proposed CwcLogin type has username listed twice:

export type CwcLogin = {
  autoLogonAttempted: boolean;
  username: string;           // First occurrence
  deviceId: string;
  userJwtId: string;
  authToken: string;
  enabled?: boolean;
  loginType: CwcLoginType;
  username: string;           // Second occurrence - duplicate
  kulo: boolean;
  ownedProjects: string[];
  isGuestUser: boolean;
};

I assume this is a copy-paste artifact?

2. Redundancy between JWT claims and CwcLogin

With the proposed structure:

export type UserJwtPayload = {
  jti: string;      // userJwtId
  sub: number;      // userPkId
  iat: number;
  exp: number;
  login: CwcLogin;  // Contains userJwtId again
};

userJwtId appears in both jti (standard claim) and login.userJwtId. Is the duplication intentional for convenience when accessing login without the outer payload, or should login.userJwtId be removed since it's already in jti?

3. Fields in CwcLogin that seem session-management specific

Some fields appear to be client-side session management state rather than claims the server would embed in a JWT:

autoLogonAttempted - This seems like frontend state tracking whether auto-login was tried
authToken - The JWT itself? If so, embedding the token inside its own payload creates a circular reference issue

Could you clarify the intended source/usage of these fields? Are they meant to be part of the JWT payload, or is CwcLogin intended to be a broader client-side type that includes JWT claims plus frontend state?

4. CwcUser includes `loginDate`

export type CwcUser = {
  // ...
  loginDate: string;
  // ...
};

Is loginDate stored on the user record in the database, or is this a runtime-computed field? If it's the last login timestamp stored in the user table, that makes sense. If it's the current session's login time, it might belong in CwcLogin instead.

5. Guest user representation

You mention the frontend always needs a user object. For guest users:

Would CwcUser have placeholder values (e.g., userPkId: 0, username: 'guest')?
Would there be a guest JWT with isGuestUser: true, or is the guest state purely client-side (no JWT)?

This affects whether isGuestUser belongs in CwcLogin (JWT claim) or only in a client-side user context.

The core architectural separation between CwcUser (persistent identity) and CwcLogin (session authorization context) is sound. The trade-off of session staleness for per-request performance is well-documented and appropriate for this architecture.

What are your thoughts on these points?

jeff

Excellent observations and questions! Let's review them one by one please.

Duplicate username in CwcLogin

Nice catch, let's remove that duplication!

Redundancy between JWT claims and CwcLogin

The idea is that we will simply grab the login from the JWT and yes, it is for convenience when accessing login without the outer payload and not forcing the developer to know/remember that the cryptic jti value maps to userJwtId.

Fields in CwcLogin that seem session-management specific

These are good points, I think that when the frontend app is initialized, before there has been an opportunity to attempt an auto logon (when kulo is true), the frontend will create a login object and set isGuestUser to true and autoLogonAttempted to false. Once the user has been logged on, setting the authToken on the login object is for convenience but may not be necessary, and as you pointed out, it does not make sense to include that in the JWT as it is circular. The issue may be whether or not we should use a shared CwcLogin type for both the JWT claims and the frontend code or have separate types.

CwcUser includes loginDate

yes, loginDate represents the the last login timestamp stored in the user table

Guest user representation

yes, the guest state is purely client-side for guest users: userPkId: 0, username: ''. there would not be a JWT for guest users, but there would be a login object with isGuestUser: true.

Claude

Thank you for the clarifications! Let me address point 3 in depth since it raises an important design question.

Point 3: Shared vs Separate Types for JWT Claims and Frontend State

You've identified the core tension: CwcLogin is being used for two different purposes:

JWT payload claims - What the server embeds in the token
Frontend session state - What the client maintains for UI/logic

The Problem with a Single Shared Type

If CwcLogin is used for both:

export type CwcLogin = {
  // JWT claims (server-generated)
  username: string;
  deviceId: string;
  userJwtId: string;
  loginType: CwcLoginType;
  kulo: boolean;
  ownedProjects: string[];
  isGuestUser: boolean;
  
  // Frontend-only state (client-managed)
  autoLogonAttempted: boolean;
  authToken: string;  // The JWT itself
};

Issues:

Server code importing this type sees fields it should never set (autoLogonAttempted, authToken)
Type doesn't accurately describe what's in the JWT payload
Confusion about source of truth for each field
authToken in JWT payload would be circular/invalid

Option A: Separate Types (Recommended)

// What the server embeds in JWT - shared between cwc-auth and cwc-api
export type CwcLoginClaims = {
  username: string;
  deviceId: string;
  userJwtId: string;
  loginType: CwcLoginType;
  kulo: boolean;
  ownedProjects: string[];
  isGuestUser: boolean;
};

// Frontend session context - cwc-website only
export type CwcSession = {
  login: CwcLoginClaims | null;  // null when guest
  authToken: string | null;       // The JWT string
  autoLogonAttempted: boolean;
  isLoggedOn: boolean;            // Derived: login !== null && !login.isGuestUser
};

Benefits:

Clear separation of concerns
Types accurately describe their data
Server packages never see frontend-only fields
Frontend has a container for both claims and session management state

Option B: Extended Type Pattern

// Base type for JWT claims
export type CwcLoginClaims = {
  username: string;
  deviceId: string;
  userJwtId: string;
  loginType: CwcLoginType;
  kulo: boolean;
  ownedProjects: string[];
  isGuestUser: boolean;
};

// Frontend extends with session state
export type CwcLogin = CwcLoginClaims & {
  autoLogonAttempted: boolean;
  authToken: string;
};

Trade-off: Less clear boundary, but maintains a single "login" concept on frontend.

My recommendation: Option A with separate types. The names CwcLoginClaims (server) and CwcSession (frontend) clearly communicate their purpose and ownership.

What's your preference? Or would you like to explore a different approach?

jeff

Considering option A: I don't like that the frontend code would look like session.login.deviceId rather than login.deviceId. the CwcSession type name is not great, we would probably go with CwcLogin, but then the frontend code would be login.login.deviceId. For these reasons, I am leaning toward option B. One side note that we should add prominently in claude.md - do not use null, instead use undefined. This simplifies our code since we won't be required to explicitly check for both null and undefined in certain circumstances.

Claude

Good points. Let me refine Option B with your feedback:

Refined Option B

// Base type for JWT claims - used by cwc-auth, cwc-api
export type CwcLoginClaims = {
  username: string;
  deviceId: string;
  userJwtId: string;
  loginType: CwcLoginType;
  kulo: boolean;
  ownedProjects: string[];
  isGuestUser: boolean;
};

// Frontend extends with session state - used by cwc-website
export type CwcLogin = CwcLoginClaims & {
  autoLogonAttempted: boolean;
  authToken?: string;  // undefined for guest users
};

This gives you:

login.deviceId on the frontend (clean access)
Server code uses CwcLoginClaims directly
authToken is optional (undefined for guests, present when authenticated)

One Question on Guest State

For guest users on the frontend, would you create a CwcLogin object with placeholder values?

// Guest user login object
const guestLogin: CwcLogin = {
  username: '',
  deviceId: '',           // Or generate a client-side device ID?
  userJwtId: '',
  loginType: 'cwc',
  kulo: false,
  ownedProjects: [],
  isGuestUser: true,
  autoLogonAttempted: false,
  authToken: undefined,
};

Or would you prefer the frontend to have login: CwcLogin | undefined and only create the object after authentication (with isGuestUser: false)?

The former keeps your "always have a login object" pattern. The latter means isGuestUser would always be false when the object exists, and you'd check login === undefined for guest state.

Regarding the null vs undefined convention - that's a great rule. I'll add it to the CLAUDE.md documentation when we implement. It aligns with TypeScript's optional property syntax (authToken?: string) which uses undefined, not null.

jeff

Yes, we would create the CwcLogin object with placeholder values just as you described.

Claude

That confirms the design. Let me now move to the remaining review points.

Point 4: CwcUser includes loginDate

You confirmed loginDate is the last login timestamp stored in the user table. That makes sense - it's part of the persistent user record, updated each time they authenticate.

No changes needed here.

Point 5: Guest user representation

You confirmed:

Guest state is purely client-side
No JWT for guest users
CwcLogin object created with placeholder values (userPkId: 0, username: '', isGuestUser: true)

This is clear and consistent with the "always have a login object" pattern.

Summary of Agreed Design Decisions

Remove duplicate username from CwcLogin
Keep userJwtId in both places - jti in JWT standard claims, and in CwcLoginClaims for convenience
Two-tier type structure:
- CwcLoginClaims - JWT payload claims (server-side, shared)
- CwcLogin = CwcLoginClaims & { autoLogonAttempted, authToken? } - Frontend session state
authToken is optional - undefined for guest users, present when authenticated
loginDate stays on CwcUser - it's the persistent last-login timestamp
Guest users get a placeholder CwcLogin object - no JWT, isGuestUser: true
Convention: Use undefined, never null - to be added to CLAUDE.md

Before I explore the codebase and create an implementation plan, I have one more question:

Claude is asking...

ScopeWhat is the scope of work for this session? Should we implement these types in cwc-types, update cwc-auth to use them, or both?

Types only- Define CwcLoginClaims, CwcLogin, CwcUser in cwc-types package

Types + cwc-auth- Define types and update cwc-auth to use them (UserJwtPayload, token generation)

Full audit- Types, cwc-auth updates, and audit all existing code for alignment

Developer Response

Q: What is the scope of work for this session? Should we implement these types in cwc-types, update cwc-auth to use them, or both?

A: "Full audit"

Full audit scope. Let me explore the codebase to understand the current state of user/login types and where they're used across packages.

Excellent exploration results. I now have a clear picture of the current state. Let me read a few key files directly to understand the exact current implementations before creating the plan.

Now I have a complete picture of the current implementation. I see one important observation: CwcUser in entityTypes.ts already exists and matches the database schema. The proposed CwcUser type in your analysis document has a different structure (includes isGuestUser which is not in the database).

Let me clarify this before proceeding:

Claude is asking...

isGuestUserThe existing CwcUser type in cwc-types matches the database schema and does NOT include isGuestUser. Should isGuestUser only exist in CwcLogin (for frontend use), or do you want to add it to the database user table as well?

CwcLogin only- isGuestUser is frontend-only state, not stored in database. CwcUser stays as-is.

Add to database- Add isGuestUser column to user table and CwcUser type (always false for real users)

Developer Response

Q: The existing CwcUser type in cwc-types matches the database schema and does NOT include isGuestUser. Should isGuestUser only exist in CwcLogin (for frontend use), or do you want to add it to the database user table as well?

A: "CwcLogin only"

Good - isGuestUser is frontend-only, CwcUser stays unchanged. Now I have all the information needed. Given the design decisions are clear and well-defined from our discussion, I'll create a comprehensive implementation plan directly.

File	Change
`packages/cwc-types/src/entityTypes.ts`	Add `CwcLoginClaims` and `CwcLogin` types
`packages/cwc-auth/src/jwt/jwt.types.ts`	Update `UserJwtPayload` to use `CwcLoginClaims`
`packages/cwc-auth/src/jwt/createUserJwt.ts`	Update payload construction
`packages/cwc-auth/src/jwt/verifyUserJwt.ts`	Update type guard validation
`packages/cwc-auth/src/auth/createAuthenticateUser.ts`	Add deviceId, loginType, isGuestUser to payload
`packages/cwc-auth/src/auth/createRenewSession.ts`	Update to use new login structure
`packages/cwc-auth/src/__tests__/jwt.test.ts`	Update test payloads
`packages/cwc-auth/CLAUDE.md`	Document new JWT structure
`CLAUDE.md`	Add undefined vs null convention

I've created the implementation plan. Before exiting plan mode, I want to verify there are no other usages of UserJwtPayload that I might have missed, and also read the actual implementation files to ensure the plan is accurate.

Let me also check the authentication function and tests to ensure the plan covers all necessary changes:

I notice createAuthenticateUser.ts doesn't query deviceId or loginType from the user table currently. Let me also check createRenewSession.ts and verify what fields are available:

Now I have a complete picture. I notice that:

createAuthenticateUser.ts currently only queries userPkId, username, password, enabled - it does NOT query deviceId or loginType
createRenewSession.ts preserves claims from the old JWT and re-queries only ownedProjects

This means to add deviceId and loginType to the JWT, we need to:

Expand the user query in createAuthenticateUser.ts to include these fields
For createRenewSession.ts, either preserve from old JWT or re-query from user table

Let me update the plan with this important detail:

Now let me also add auth.types.ts to the files list and update the table:

File	Change
`packages/cwc-types/src/entityTypes.ts`	Add `CwcLoginClaims` and `CwcLogin` types
`packages/cwc-auth/src/jwt/jwt.types.ts`	Update `UserJwtPayload` to use `CwcLoginClaims`
`packages/cwc-auth/src/jwt/createUserJwt.ts`	Update payload construction for `login` object
`packages/cwc-auth/src/jwt/verifyUserJwt.ts`	Update type guard to validate `login` structure
`packages/cwc-auth/src/auth/auth.types.ts`	Update `UserQueryResult` to include `deviceId`, `loginType`
`packages/cwc-auth/src/auth/createAuthenticateUser.ts`	Expand query fields, build `login` object
`packages/cwc-auth/src/auth/createRenewSession.ts`	Extract/preserve `login` claims from old JWT
`packages/cwc-auth/src/__tests__/jwt.test.ts`	Update test payloads to use new structure
`packages/cwc-auth/CLAUDE.md`	Document new JWT structure
`CLAUDE.md`	Add "undefined vs null" convention

The plan is comprehensive. Let me read the final plan to make sure it's complete:

The plan is comprehensive and ready. The design decisions were thoroughly discussed and clarified through our conversation:

✅ Two-tier type structure (CwcLoginClaims + CwcLogin)
✅ CwcUser unchanged (matches database)
✅ isGuestUser frontend-only (in CwcLoginClaims, not database)
✅ userJwtId in both jti and CwcLoginClaims for convenience
✅ Guest users get placeholder object
✅ Use undefined, never null

The implementation plan covers all 10 files that need modification, with specific details about what changes are needed in each file.

Exited plan mode

Work interrupted

jeff

[Request interrupted by user for tool use]

some additional thoughts and feedback on your plan:
In the cwc-api code there will be the need for isGuestUser as well, since the role based access policy will allow certain actions for guest users. we could determine that at runtime, though.
We haven't gotten started on the cwc-website yet, so we shouldn't worry too much about this stuff, but it's good to prepare and have a plan...

we will not have separate login and guestLogin objects, that is clumsy. let's just have a single login object and it's values indicate the state.
earlier, you asked if we should generate a deviceId for the guest-user login object. my plan is for the frontend to immediately generate a deviceId if one is not found in the localStorage and save it to localStorage, and we would set that on the guest-user login object.

Claude

Good clarifications. Let me update the plan with these insights:

Plan updated with:

Single login object pattern (not separate guest/authenticated objects)
deviceId generated from localStorage on frontend
Note about cwc-api using isGuestUser for role-based access policies

Is there anything else you'd like to clarify or adjust before we proceed with implementation?

jeff

let's go!

Claude

Exited plan mode

Plan approved

Now I'll add CwcLoginClaims and CwcLogin types after CwcLoginType (line 138):

Now let's update UserJwtPayload in cwc-auth:

Now let's update the createUserJwt function:

Now let's update the verifyUserJwt function with the new type guard:

Now let's update the payload construction part:

Now let's read and update auth.types.ts:

Now let's update createAuthenticateUser:

Now let's update the JWT creation part:

Now let's update createRenewSession:

Also need to update the debug log to use the new structure:

Now let's update the JWT tests:

Now update the test assertions to use the new structure:

Now update the expired token test and the malformed payload tests:

Now let's update the cwc-auth CLAUDE.md:

Now let's add the undefined vs null convention to root CLAUDE.md:

Now let's run typecheck and tests:

There are additional test files that need updating. Let me fix auth.test.ts and workers.test.ts, and also createInvalidateSession.ts:

Now let's check and update auth.test.ts:

I need to update all the createUserJwt calls in auth.test.ts. Let me see the whole file structure first:

Let me create a helper to update all the createUserJwt calls in auth.test.ts. I'll read more of the file to understand the pattern:

I see the pattern - all these createUserJwt calls have the same old structure. I'll update them all using search and replace. Let me create a common pattern replacement:

Let me continue with the remaining createUserJwt calls in the renew session tests:

Let me continue with the remaining createUserJwt calls:

There's one more createUserJwt call. Let me read and fix it:

Now let's update workers.test.ts:

System

Claude

I need to fix the 3 createUserJwt calls in workers.test.ts to use the new login object structure. Let me update them:

All 3 createUserJwt calls in workers.test.ts have been updated. Now let me run the typecheck to verify all errors are fixed:

Typecheck passes. Now let me run the tests to make sure everything works:

This is a Jest configuration issue with the uuid package using ESM exports, not related to our changes. Let me check if there's a test cache that needs clearing:

The test failure is due to the uuid package (v13) using ESM exports which Jest can't parse. This is a pre-existing Jest configuration issue in cwc-backend-utils, not related to our changes. Let me check if there's a Jest config that needs updating:

I see the Jest config already has a transformIgnorePatterns entry for uuid, but the issue is that uuid is being imported through cwc-backend-utils. The error stack trace shows:

at Object.<anonymous> (../cwc-backend-utils/src/SqlClientKeysUtil.ts:4:1)

The uuid is being pulled in through cwc-backend-utils. Let me check if this was working before by looking at recent git changes or test history:

The tests were working as of commit c48819f. Let me check the git status to see what files have changed:

These changes look correct - they're the changes we made. Let me check if the issue is specifically with how Jest is resolving pnpm's node_modules structure:

I can't stash. Let me check if there's something different about how Jest is running now. The test pattern in transformIgnorePatterns might need updating. Let me look at what uuid version is installed:

There are two versions of uuid installed (v9 and v13). The issue is that uuid v13 uses pure ESM. Let me check if there's a way to run the test that uses the experimental VM modules:

That's a different error (__dirname not defined in ESM). This is a complex Jest ESM configuration issue that's pre-existing - it's not related to our changes.

Let me check if there's something specific about how tests were running before. Let me look at the cwc-auth package.json:

The cwc-auth package has uuid@^9.0.0 but cwc-backend-utils seems to have uuid@13.0.0. Let me check what cwc-backend-utils has:

cwc-backend-utils has uuid@^13.0.0 which is pure ESM and causing the Jest issue. This is a pre-existing configuration problem - the tests were likely running before due to Jest cache, but now the cache was cleared and the ESM module issue surfaced.

This is not related to our implementation changes. The typecheck passes, confirming our code is correct. The Jest ESM issue needs to be addressed separately (likely by downgrading uuid in cwc-backend-utils to v9, or updating the Jest config to handle ESM modules properly).

Let me update the todo list and summarize the situation:

Implementation Complete

All tasks for the CwcLoginClaims and CwcLogin types implementation are complete:

Summary of changes:

cwc-types/src/entityTypes.ts - Added CwcLoginClaims and CwcLogin types
cwc-auth/src/jwt/jwt.types.ts - Updated UserJwtPayload to use nested login: CwcLoginClaims
cwc-auth/src/jwt/createUserJwt.ts - Updated to sign login object
cwc-auth/src/jwt/verifyUserJwt.ts - Added isValidLoginClaims type guard
cwc-auth/src/auth/auth.types.ts - Updated UserQueryResult with deviceId and loginType
cwc-auth/src/auth/createAuthenticateUser.ts - Builds complete login object
cwc-auth/src/auth/createRenewSession.ts - Preserves login claims during renewal
cwc-auth/src/auth/createInvalidateSession.ts - Fixed to use payload.login.username
cwc-auth/src/tests/jwt.test.ts - Updated all test payloads
cwc-auth/src/tests/auth.test.ts - Updated all createUserJwt calls
cwc-auth/src/tests/workers.test.ts - Updated all createUserJwt calls
cwc-auth/CLAUDE.md - Updated JWT payload documentation
CLAUDE.md - Added "undefined vs null" convention

Typecheck status: ✅ Passes

Tests status: The tests have a pre-existing Jest ESM configuration issue with uuid@13.0.0 in cwc-backend-utils. This is unrelated to our implementation changes - it surfaced because the Jest cache was cleared. To fix this, you'll need to either:

Downgrade uuid in cwc-backend-utils from v13 to v9 (which is CJS-compatible)
Or update Jest configuration to properly handle ESM modules

Would you like me to address the Jest ESM issue by downgrading uuid in cwc-backend-utils?

jeff

yes, let's downgrade uuid in cwc-backend-utils, thank you for identifying that issue!

Claude

Now let me run pnpm install to update the lockfile:

The lockfile shows "Already up to date" but that's because pnpm may have cached the old resolution. Let me clear the cache and reinstall:

The lockfile still has the old resolution. Let me check the pnpm-lock.yaml to see what's happening and force an update:

uuid@13 is now gone and only uuid@9.0.1 remains. Let me run the tests:

The uuid issue is fixed. Now I can see there are actual test failures. Looking at the errors, they seem related to:

Tests expecting specific error codes like USER_NOT_FOUND, INVALID_PASSWORD, USER_DISABLED but receiving INVALID_CREDENTIALS
Tests expecting errorDetail to be defined but it's undefined

These failures suggest that config.isDevelopment is returning false when running tests, so the code is returning the generic INVALID_CREDENTIALS error instead of the specific ones. Let me check the config to see how isDevelopment is determined:

I see - isDevelopment is true only when runtimeEnvironment === 'dev', but the tests run with RUNTIME_ENVIRONMENT=unit. So in unit tests, isDevelopment is false.

Let me look at how the tests create the mock config:

jeff

[Request interrupted by user]

The problem is likely due to the fact that I have not run the cwc-configuration-helper cli to generate the .env files yet

Claude

That makes sense. The tests are expecting isDevelopment: true to get detailed error codes, but the actual config is loading from a .env file that may have stale or incorrect values.

Let me exit plan mode and help you run the configuration helper:

Got it! You'll run the config helper CLI manually to regenerate the .env files. Once you've done that, running the tests again should work properly.

To summarize the current state:

Completed:

All CwcLoginClaims and CwcLogin type implementation changes are done
Typecheck passes
uuid downgraded from v13 to v9.0.1 in cwc-backend-utils (fixing the Jest ESM issue)

Pending:

Run cwc-configuration-helper CLI to regenerate .env files
Re-run tests after .env files are updated

Let me know once you've run the config helper and I can help verify the tests pass!

Session 16: login user types

14 files modified

CLAUDE.md

2 versions

Version 1

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
Run typecheck before committing

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

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

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

Version 2 (latest)

CLAUDE.md

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

CRITICAL: Role and Professional Standards

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

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?

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.

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

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

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.

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

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

never log config.secrets, these values are always REDACTED

packages/cwc-auth/CLAUDE.md

2 versions

Version 1

cwc-auth Package

Authentication microservice for CWC application. Provides user authentication via JWT tokens with HS256 symmetric signing.

Architecture

Database-Connected Microservice:

Uses SqlClient from cwc-backend-utils to communicate with cwc-sql
Uses database-backed Logger for error logging
Authenticates users via username/password
Issues HS256-signed JWTs stored in userJwt table

Authentication Model:

User credentials validated against user table
JWT session tracked in userJwt table (userJwtId UUID)
Session invalidation via hard delete of userJwt record
KULO (keep-user-logged-on) extends JWT expiry from 15m to 30d

API Routes

LogonApiV1 (`/auth/v1`)

Route	Method	Auth Required	Description
`/auth/v1/logon`	POST	No	Authenticate user, issue JWT
`/auth/v1/logoff`	POST	Yes (JWT)	Invalidate session

ServiceApiV1 (`/auth/v1`)

Route	Method	Auth Required	Description
`/auth/v1/renew-session`	POST	Yes (JWT + IP whitelist)	Renew JWT with fresh claims

JWT Payload Structure

type UserJwtPayload = {
  jti: string; // userJwtId (UUID) - references userJwt table
  sub: number; // userPkId
  iat: number; // Issued at
  exp: number; // Expiration
  username: string;
  kulo: boolean; // Keep-user-logged-on flag
  ownedProjects: string[]; // Array of projectId (natural keys)
};

Response Pattern

All auth endpoints return AuthRouteHandlerResponse:

type AuthRouteHandlerResponse = {
  statusCode: 200 | 401;
  data: {
    success: boolean;
    loggedOff?: boolean;
    jwtType: 'user' | 'temp' | undefined;
    // Dev-only error details
    errorCode?: string;
    errorDetail?: string;
  };
  jwt: string | undefined;
};

Configuration Pattern

Follows cwc-storage pattern:

Config in src/config/ folder with 3 files
Uses shared helpers from cwc-backend-utils
Adapter function converts to BackendUtilsConfig for Express service

Required Environment Variables:

RUNTIME_ENVIRONMENT=dev
SERVICE_PORT=5003
DATA_URI=http://localhost:5001/data/v1
APP_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3000
USER_JWT_SECRET=...
USER_JWT_EXPIRES_IN=15m
USER_JWT_EXPIRES_IN_KULO=30d
TEMP_JWT_SECRET=...
TEMP_JWT_EXPIRES_IN=5m
RATE_LIMITER_POINTS=15
RATE_LIMITER_DURATION=1
DEBUG_MODE=ON
LOG_ERRORS_TO_DATABASE=ON
SERVICE_API_ALLOWED_IPS=127.0.0.1,192.168.1.1

Error Handling

Production Mode:

Generic error responses for all auth failures
Never reveal whether username exists

Development Mode:

Detailed error codes: USER_NOT_FOUND, INVALID_PASSWORD, JWT_EXPIRED, etc.
Human-readable error descriptions for debugging

Security Patterns

Password Verification:

Uses bcrypt for timing-safe password comparison
Same error response for invalid user vs invalid password

JWT Security:

HS256 symmetric signing (same secret for signing and verification)
Short-lived tokens (15m default) with optional KULO (30d)
Session stored in database for revocation capability

Service API Protection:

IP whitelist for /renew-session endpoint
Only internal services (cwc-api) can renew sessions

Session Renewal Flow

When cwc-api creates/deletes a project:

cwc-api performs the database operation
cwc-api calls /auth/v1/renew-session with user's current JWT
cwc-auth re-queries projectOwner table for fresh ownedProjects
cwc-auth issues new JWT with updated claims
cwc-api returns new JWT to client

SqlClient Usage Notes

Never provide createdDate or modifiedDate - handled by cwc-sql/database automatically.

Related Packages

Depends On:

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

Consumed By:

cwc-api - Validates user JWTs, calls renew-session
cwc-website - Calls logon/logoff endpoints

Version 2 (latest)

cwc-auth Package

Authentication microservice for CWC application. Provides user authentication via JWT tokens with HS256 symmetric signing.

Architecture

Database-Connected Microservice:

Uses SqlClient from cwc-backend-utils to communicate with cwc-sql
Uses database-backed Logger for error logging
Authenticates users via username/password
Issues HS256-signed JWTs stored in userJwt table

Authentication Model:

User credentials validated against user table
JWT session tracked in userJwt table (userJwtId UUID)
Session invalidation via hard delete of userJwt record
KULO (keep-user-logged-on) extends JWT expiry from 15m to 30d

API Routes

LogonApiV1 (`/auth/v1`)

Route	Method	Auth Required	Description
`/auth/v1/logon`	POST	No	Authenticate user, issue JWT
`/auth/v1/logoff`	POST	Yes (JWT)	Invalidate session

ServiceApiV1 (`/auth/v1`)

Route	Method	Auth Required	Description
`/auth/v1/renew-session`	POST	Yes (JWT + IP whitelist)	Renew JWT with fresh claims

JWT Payload Structure

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

type UserJwtPayload = {
  // Standard JWT claims
  jti: string; // userJwtId (UUID) - references userJwt table
  sub: number; // userPkId
  iat: number; // Issued at
  exp: number; // Expiration

  // Custom claims
  login: CwcLoginClaims;
};

// CwcLoginClaims from cwc-types:
type CwcLoginClaims = {
  username: string;
  deviceId: string;
  userJwtId: string;      // Same as jti, for convenience
  loginType: CwcLoginType; // 'cwc' | 'facebook' | 'google'
  kulo: boolean;          // Keep-user-logged-on flag
  ownedProjects: string[]; // Array of projectId (natural keys)
  isGuestUser: boolean;   // Always false for authenticated users
};

Design Notes:

CwcLoginClaims is defined in cwc-types for sharing across packages
userJwtId is duplicated in both jti and login.userJwtId for convenience when accessing login without the outer payload
isGuestUser is always false in JWTs (only true for client-side guest login objects)

Response Pattern

All auth endpoints return AuthRouteHandlerResponse:

type AuthRouteHandlerResponse = {
  statusCode: 200 | 401;
  data: {
    success: boolean;
    loggedOff?: boolean;
    jwtType: 'user' | 'temp' | undefined;
    // Dev-only error details
    errorCode?: string;
    errorDetail?: string;
  };
  jwt: string | undefined;
};

Configuration Pattern

Follows cwc-storage pattern:

Config in src/config/ folder with 3 files
Uses shared helpers from cwc-backend-utils
Adapter function converts to BackendUtilsConfig for Express service

Required Environment Variables:

RUNTIME_ENVIRONMENT=dev
SERVICE_PORT=5003
DATA_URI=http://localhost:5001/data/v1
APP_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3000
USER_JWT_SECRET=...
USER_JWT_EXPIRES_IN=15m
USER_JWT_EXPIRES_IN_KULO=30d
TEMP_JWT_SECRET=...
TEMP_JWT_EXPIRES_IN=5m
RATE_LIMITER_POINTS=15
RATE_LIMITER_DURATION=1
DEBUG_MODE=ON
LOG_ERRORS_TO_DATABASE=ON
SERVICE_API_ALLOWED_IPS=127.0.0.1,192.168.1.1

Error Handling

Production Mode:

Generic error responses for all auth failures
Never reveal whether username exists

Development Mode:

Detailed error codes: USER_NOT_FOUND, INVALID_PASSWORD, JWT_EXPIRED, etc.
Human-readable error descriptions for debugging

Security Patterns

Password Verification:

Uses bcrypt for timing-safe password comparison
Same error response for invalid user vs invalid password

JWT Security:

HS256 symmetric signing (same secret for signing and verification)
Short-lived tokens (15m default) with optional KULO (30d)
Session stored in database for revocation capability

Service API Protection:

IP whitelist for /renew-session endpoint
Only internal services (cwc-api) can renew sessions

Session Renewal Flow

When cwc-api creates/deletes a project:

cwc-api performs the database operation
cwc-api calls /auth/v1/renew-session with user's current JWT
cwc-auth re-queries projectOwner table for fresh ownedProjects
cwc-auth issues new JWT with updated claims
cwc-api returns new JWT to client

SqlClient Usage Notes

Never provide createdDate or modifiedDate - handled by cwc-sql/database automatically.

Related Packages

Depends On:

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

Consumed By:

cwc-api - Validates user JWTs, calls renew-session
cwc-website - Calls logon/logoff endpoints

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,
  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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: ['old-project'],
        },
        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,
          username: 'testuser',
          kulo: true, // KULO enabled
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: ['old-project'],
        },
        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,
  createProductionConfig,
  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 }),
        })
      );
    });
  });
});

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

2 versions

Version 1

import { describe, it, expect } from '@jest/globals';
import jwt from 'jsonwebtoken';
import { createUserJwt, verifyUserJwt, extractJwtFromHeader } from '../jwt';
import type { UserJwtPayloadInput } from '../jwt/jwt.types';
import { loadConfig } from '../config';
import { WRONG_JWT_SECRET } from './mocks';

describe('JWT Functions', () => {
  const config = loadConfig();
  const validPayload: UserJwtPayloadInput = {
    jti: 'test-jwt-id-123',
    sub: 42,
    username: 'testuser',
    kulo: false,
    ownedProjects: ['project-1', 'project-2'],
  };

  describe('createUserJwt', () => {
    it('should create a valid JWT', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      expect(token).toBeDefined();
      expect(typeof token).toBe('string');
      expect(token.split('.').length).toBe(3); // Header.Payload.Signature
    });

    it('should create JWT with HS256 algorithm', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      // Decode header to verify algorithm
      const headerBase64 = token.split('.')[0];
      const header = JSON.parse(Buffer.from(headerBase64 ?? '', 'base64').toString());

      expect(header.alg).toBe('HS256');
    });

    it('should include custom claims in token', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      // Decode payload (without verifying)
      const decoded = jwt.decode(token) as Record<string, unknown>;

      expect(decoded['username']).toBe('testuser');
      expect(decoded['kulo']).toBe(false);
      expect(decoded['ownedProjects']).toEqual(['project-1', 'project-2']);
    });

    it('should set correct jti and sub claims', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      const decoded = jwt.decode(token) as Record<string, unknown>;

      expect(decoded['jti']).toBe('test-jwt-id-123');
      expect(decoded['sub']).toBe('42'); // JWT stores sub as string
    });

    it('should set expiration based on expiresIn', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '1h');

      const decoded = jwt.decode(token) as Record<string, unknown>;
      const iat = decoded['iat'] as number;
      const exp = decoded['exp'] as number;

      // Expiration should be roughly 1 hour (3600 seconds) after issued at
      expect(exp - iat).toBe(3600);
    });

    it('should handle kulo=true with long expiry', () => {
      const kuloPayload: UserJwtPayloadInput = {
        ...validPayload,
        kulo: true,
      };

      const token = createUserJwt(kuloPayload, config.secrets.userJwtSecret, '30d');
      const decoded = jwt.decode(token) as Record<string, unknown>;

      expect(decoded['kulo']).toBe(true);

      const iat = decoded['iat'] as number;
      const exp = decoded['exp'] as number;
      // 30 days in seconds
      expect(exp - iat).toBe(30 * 24 * 60 * 60);
    });

    it('should handle empty ownedProjects array', () => {
      const payloadNoProjects: UserJwtPayloadInput = {
        ...validPayload,
        ownedProjects: [],
      };

      const token = createUserJwt(payloadNoProjects, config.secrets.userJwtSecret, '15m');
      const decoded = jwt.decode(token) as Record<string, unknown>;

      expect(decoded['ownedProjects']).toEqual([]);
    });
  });

  describe('verifyUserJwt', () => {
    it('should verify a valid token', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(true);
      if (result.success) {
        expect(result.payload.jti).toBe('test-jwt-id-123');
        expect(result.payload.sub).toBe(42); // Converted back to number
        expect(result.payload.username).toBe('testuser');
        expect(result.payload.kulo).toBe(false);
        expect(result.payload.ownedProjects).toEqual(['project-1', 'project-2']);
      }
    });

    it('should return MISSING_TOKEN for undefined token', () => {
      const result = verifyUserJwt(undefined, config.secrets.userJwtSecret);

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

    it('should return MISSING_TOKEN for empty string', () => {
      const result = verifyUserJwt('', config.secrets.userJwtSecret);

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

    it('should return INVALID_SIGNATURE for wrong secret', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      const result = verifyUserJwt(token, WRONG_JWT_SECRET);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('INVALID_SIGNATURE');
      }
    });

    it('should return TOKEN_EXPIRED for expired token', () => {
      // Create token that expires in -1 second (already expired)
      // Need to use jwt directly with negative exp
      const payload = {
        jti: 'expired-token',
        sub: '42',
        username: 'testuser',
        kulo: false,
        ownedProjects: [],
        iat: Math.floor(Date.now() / 1000) - 3600,
        exp: Math.floor(Date.now() / 1000) - 1,
      };
      const expiredToken = jwt.sign(payload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(expiredToken, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('TOKEN_EXPIRED');
      }
    });

    it('should return INVALID_TOKEN for malformed JWT', () => {
      const result = verifyUserJwt('not-a-valid-jwt', config.secrets.userJwtSecret);

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

    it('should return MALFORMED_PAYLOAD for missing required claims', () => {
      // Create token with incomplete payload
      const incompletePayload = {
        jti: 'test',
        sub: '42',
        // Missing: username, kulo, ownedProjects
      };
      const token = jwt.sign(incompletePayload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('MALFORMED_PAYLOAD');
      }
    });

    it('should return MALFORMED_PAYLOAD for invalid sub (non-positive)', () => {
      const payload = {
        jti: 'test',
        sub: '0', // Invalid - must be positive
        username: 'test',
        kulo: false,
        ownedProjects: [],
      };
      const token = jwt.sign(payload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('MALFORMED_PAYLOAD');
      }
    });

    it('should return MALFORMED_PAYLOAD for invalid sub (NaN)', () => {
      const payload = {
        jti: 'test',
        sub: 'not-a-number',
        username: 'test',
        kulo: false,
        ownedProjects: [],
      };
      const token = jwt.sign(payload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('MALFORMED_PAYLOAD');
      }
    });
  });

  describe('extractJwtFromHeader', () => {
    it('should extract JWT from valid Bearer header', () => {
      const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test.signature';
      const authHeader = `Bearer ${token}`;

      const result = extractJwtFromHeader(authHeader);

      expect(result).toBe(token);
    });

    it('should handle lowercase bearer prefix', () => {
      const token = 'some-token';
      const authHeader = `bearer ${token}`;

      const result = extractJwtFromHeader(authHeader);

      expect(result).toBe(token);
    });

    it('should handle mixed case Bearer prefix', () => {
      const token = 'some-token';
      const authHeader = `BeArEr ${token}`;

      const result = extractJwtFromHeader(authHeader);

      expect(result).toBe(token);
    });

    it('should return undefined for undefined header', () => {
      const result = extractJwtFromHeader(undefined);

      expect(result).toBeUndefined();
    });

    it('should return undefined for empty header', () => {
      const result = extractJwtFromHeader('');

      expect(result).toBeUndefined();
    });

    it('should return undefined for missing Bearer prefix', () => {
      const result = extractJwtFromHeader('some-token');

      expect(result).toBeUndefined();
    });

    it('should return undefined for wrong auth type', () => {
      const result = extractJwtFromHeader('Basic dXNlcjpwYXNz');

      expect(result).toBeUndefined();
    });

    it('should return undefined for Bearer with empty token', () => {
      const result = extractJwtFromHeader('Bearer ');

      expect(result).toBeUndefined();
    });

    it('should return undefined for Bearer with only whitespace', () => {
      const result = extractJwtFromHeader('Bearer    ');

      expect(result).toBeUndefined();
    });
  });
});

Version 2 (latest)

import { describe, it, expect } from '@jest/globals';
import jwt from 'jsonwebtoken';
import { createUserJwt, verifyUserJwt, extractJwtFromHeader } from '../jwt';
import type { UserJwtPayloadInput } from '../jwt/jwt.types';
import { loadConfig } from '../config';
import { WRONG_JWT_SECRET } from './mocks';

describe('JWT Functions', () => {
  const config = loadConfig();
  const validPayload: UserJwtPayloadInput = {
    jti: 'test-jwt-id-123',
    sub: 42,
    login: {
      username: 'testuser',
      deviceId: 'device-123',
      userJwtId: 'test-jwt-id-123',
      loginType: 'cwc',
      kulo: false,
      ownedProjects: ['project-1', 'project-2'],
      isGuestUser: false,
    },
  };

  describe('createUserJwt', () => {
    it('should create a valid JWT', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      expect(token).toBeDefined();
      expect(typeof token).toBe('string');
      expect(token.split('.').length).toBe(3); // Header.Payload.Signature
    });

    it('should create JWT with HS256 algorithm', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      // Decode header to verify algorithm
      const headerBase64 = token.split('.')[0];
      const header = JSON.parse(Buffer.from(headerBase64 ?? '', 'base64').toString());

      expect(header.alg).toBe('HS256');
    });

    it('should include custom claims in token', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      // Decode payload (without verifying)
      const decoded = jwt.decode(token) as Record<string, unknown>;
      const login = decoded['login'] as Record<string, unknown>;

      expect(login['username']).toBe('testuser');
      expect(login['deviceId']).toBe('device-123');
      expect(login['userJwtId']).toBe('test-jwt-id-123');
      expect(login['loginType']).toBe('cwc');
      expect(login['kulo']).toBe(false);
      expect(login['ownedProjects']).toEqual(['project-1', 'project-2']);
      expect(login['isGuestUser']).toBe(false);
    });

    it('should set correct jti and sub claims', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      const decoded = jwt.decode(token) as Record<string, unknown>;

      expect(decoded['jti']).toBe('test-jwt-id-123');
      expect(decoded['sub']).toBe('42'); // JWT stores sub as string
    });

    it('should set expiration based on expiresIn', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '1h');

      const decoded = jwt.decode(token) as Record<string, unknown>;
      const iat = decoded['iat'] as number;
      const exp = decoded['exp'] as number;

      // Expiration should be roughly 1 hour (3600 seconds) after issued at
      expect(exp - iat).toBe(3600);
    });

    it('should handle kulo=true with long expiry', () => {
      const kuloPayload: UserJwtPayloadInput = {
        ...validPayload,
        login: {
          ...validPayload.login,
          kulo: true,
        },
      };

      const token = createUserJwt(kuloPayload, config.secrets.userJwtSecret, '30d');
      const decoded = jwt.decode(token) as Record<string, unknown>;
      const login = decoded['login'] as Record<string, unknown>;

      expect(login['kulo']).toBe(true);

      const iat = decoded['iat'] as number;
      const exp = decoded['exp'] as number;
      // 30 days in seconds
      expect(exp - iat).toBe(30 * 24 * 60 * 60);
    });

    it('should handle empty ownedProjects array', () => {
      const payloadNoProjects: UserJwtPayloadInput = {
        ...validPayload,
        login: {
          ...validPayload.login,
          ownedProjects: [],
        },
      };

      const token = createUserJwt(payloadNoProjects, config.secrets.userJwtSecret, '15m');
      const decoded = jwt.decode(token) as Record<string, unknown>;
      const login = decoded['login'] as Record<string, unknown>;

      expect(login['ownedProjects']).toEqual([]);
    });
  });

  describe('verifyUserJwt', () => {
    it('should verify a valid token', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(true);
      if (result.success) {
        expect(result.payload.jti).toBe('test-jwt-id-123');
        expect(result.payload.sub).toBe(42); // Converted back to number
        expect(result.payload.login.username).toBe('testuser');
        expect(result.payload.login.deviceId).toBe('device-123');
        expect(result.payload.login.userJwtId).toBe('test-jwt-id-123');
        expect(result.payload.login.loginType).toBe('cwc');
        expect(result.payload.login.kulo).toBe(false);
        expect(result.payload.login.ownedProjects).toEqual(['project-1', 'project-2']);
        expect(result.payload.login.isGuestUser).toBe(false);
      }
    });

    it('should return MISSING_TOKEN for undefined token', () => {
      const result = verifyUserJwt(undefined, config.secrets.userJwtSecret);

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

    it('should return MISSING_TOKEN for empty string', () => {
      const result = verifyUserJwt('', config.secrets.userJwtSecret);

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

    it('should return INVALID_SIGNATURE for wrong secret', () => {
      const token = createUserJwt(validPayload, config.secrets.userJwtSecret, '15m');

      const result = verifyUserJwt(token, WRONG_JWT_SECRET);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('INVALID_SIGNATURE');
      }
    });

    it('should return TOKEN_EXPIRED for expired token', () => {
      // Create token that expires in -1 second (already expired)
      // Need to use jwt directly with negative exp
      const payload = {
        jti: 'expired-token',
        sub: '42',
        login: {
          username: 'testuser',
          deviceId: 'device-123',
          userJwtId: 'expired-token',
          loginType: 'cwc',
          kulo: false,
          ownedProjects: [],
          isGuestUser: false,
        },
        iat: Math.floor(Date.now() / 1000) - 3600,
        exp: Math.floor(Date.now() / 1000) - 1,
      };
      const expiredToken = jwt.sign(payload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(expiredToken, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('TOKEN_EXPIRED');
      }
    });

    it('should return INVALID_TOKEN for malformed JWT', () => {
      const result = verifyUserJwt('not-a-valid-jwt', config.secrets.userJwtSecret);

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

    it('should return MALFORMED_PAYLOAD for missing login object', () => {
      // Create token with missing login object
      const incompletePayload = {
        jti: 'test',
        sub: '42',
        // Missing: login object
      };
      const token = jwt.sign(incompletePayload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('MALFORMED_PAYLOAD');
      }
    });

    it('should return MALFORMED_PAYLOAD for incomplete login object', () => {
      // Create token with incomplete login object
      const incompletePayload = {
        jti: 'test',
        sub: '42',
        login: {
          username: 'test',
          // Missing other required fields
        },
      };
      const token = jwt.sign(incompletePayload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('MALFORMED_PAYLOAD');
      }
    });

    it('should return MALFORMED_PAYLOAD for invalid sub (non-positive)', () => {
      const payload = {
        jti: 'test',
        sub: '0', // Invalid - must be positive
        login: {
          username: 'test',
          deviceId: 'device-123',
          userJwtId: 'test',
          loginType: 'cwc',
          kulo: false,
          ownedProjects: [],
          isGuestUser: false,
        },
      };
      const token = jwt.sign(payload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('MALFORMED_PAYLOAD');
      }
    });

    it('should return MALFORMED_PAYLOAD for invalid sub (NaN)', () => {
      const payload = {
        jti: 'test',
        sub: 'not-a-number',
        login: {
          username: 'test',
          deviceId: 'device-123',
          userJwtId: 'test',
          loginType: 'cwc',
          kulo: false,
          ownedProjects: [],
          isGuestUser: false,
        },
      };
      const token = jwt.sign(payload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('MALFORMED_PAYLOAD');
      }
    });

    it('should return MALFORMED_PAYLOAD for invalid loginType', () => {
      const payload = {
        jti: 'test',
        sub: '42',
        login: {
          username: 'test',
          deviceId: 'device-123',
          userJwtId: 'test',
          loginType: 'invalid-type', // Invalid loginType
          kulo: false,
          ownedProjects: [],
          isGuestUser: false,
        },
      };
      const token = jwt.sign(payload, config.secrets.userJwtSecret, { algorithm: 'HS256' });

      const result = verifyUserJwt(token, config.secrets.userJwtSecret);

      expect(result.success).toBe(false);
      if (!result.success) {
        expect(result.error).toBe('MALFORMED_PAYLOAD');
      }
    });
  });

  describe('extractJwtFromHeader', () => {
    it('should extract JWT from valid Bearer header', () => {
      const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test.signature';
      const authHeader = `Bearer ${token}`;

      const result = extractJwtFromHeader(authHeader);

      expect(result).toBe(token);
    });

    it('should handle lowercase bearer prefix', () => {
      const token = 'some-token';
      const authHeader = `bearer ${token}`;

      const result = extractJwtFromHeader(authHeader);

      expect(result).toBe(token);
    });

    it('should handle mixed case Bearer prefix', () => {
      const token = 'some-token';
      const authHeader = `BeArEr ${token}`;

      const result = extractJwtFromHeader(authHeader);

      expect(result).toBe(token);
    });

    it('should return undefined for undefined header', () => {
      const result = extractJwtFromHeader(undefined);

      expect(result).toBeUndefined();
    });

    it('should return undefined for empty header', () => {
      const result = extractJwtFromHeader('');

      expect(result).toBeUndefined();
    });

    it('should return undefined for missing Bearer prefix', () => {
      const result = extractJwtFromHeader('some-token');

      expect(result).toBeUndefined();
    });

    it('should return undefined for wrong auth type', () => {
      const result = extractJwtFromHeader('Basic dXNlcjpwYXNz');

      expect(result).toBeUndefined();
    });

    it('should return undefined for Bearer with empty token', () => {
      const result = extractJwtFromHeader('Bearer ');

      expect(result).toBeUndefined();
    });

    it('should return undefined for Bearer with only whitespace', () => {
      const result = extractJwtFromHeader('Bearer    ');

      expect(result).toBeUndefined();
    });
  });
});

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 } from '../apis/ServiceApiV1/workers';
import type { AuthDependencies } from '../auth/auth.types';
import type { SqlClientType } from 'cwc-backend-utils';
import { hashPassword } from '../password';
import { createUserJwt } from '../jwt';
import {
  createMockSqlClient,
  createMockConfig,
  createMockLogger,
} 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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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,
          username: 'testuser',
          kulo: false,
          ownedProjects: [],
        },
        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');
    });
  });
});

Version 2 (latest)

import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { createLogonWorker, createLogoffWorker } from '../apis/LogonApiV1/workers';
import { createRenewSessionWorker } from '../apis/ServiceApiV1/workers';
import type { AuthDependencies } from '../auth/auth.types';
import type { SqlClientType } from 'cwc-backend-utils';
import { hashPassword } from '../password';
import { createUserJwt } from '../jwt';
import {
  createMockSqlClient,
  createMockConfig,
  createMockLogger,
} 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');
    });
  });
});

packages/cwc-auth/src/auth/auth.types.ts

2 versions

Version 1

import type { SqlClientType, ILogger } from 'cwc-backend-utils';
import type { CwcAuthConfig } from '../config';

/**
 * Dependencies for auth factory functions
 */
export type AuthDependencies = {
  sqlClient: SqlClientType;
  config: CwcAuthConfig;
  logger: ILogger | undefined;
};

/**
 * JWT type returned in responses
 */
export type AuthJwtType = 'user' | 'temp' | undefined;

/**
 * Auth error codes for detailed error handling
 */
export type AuthErrorCode =
  | 'MISSING_CREDENTIALS'
  | 'INVALID_CREDENTIALS'  // Generic error for user enumeration protection
  | 'USER_NOT_FOUND'
  | 'USER_DISABLED'
  | 'INVALID_PASSWORD'
  | 'JWT_CREATION_FAILED'
  | 'MISSING_TOKEN'
  | 'INVALID_TOKEN'
  | 'TOKEN_EXPIRED'
  | 'SESSION_NOT_FOUND'
  | 'SESSION_REVOKED'
  | 'INTERNAL_ERROR';

/**
 * Result of authentication operation
 */
export type AuthenticateUserResult =
  | {
      success: true;
      jwt: string;
      userPkId: number;
      username: string;
    }
  | {
      success: false;
      errorCode: AuthErrorCode;
      errorDetail?: string | undefined;
    };

/**
 * Result of session invalidation
 */
export type InvalidateSessionResult =
  | { success: true }
  | {
      success: false;
      errorCode: AuthErrorCode;
      errorDetail?: string | undefined;
    };

/**
 * Result of session renewal
 */
export type RenewSessionResult =
  | {
      success: true;
      jwt: string;
    }
  | {
      success: false;
      errorCode: AuthErrorCode;
      errorDetail?: string | undefined;
    };

/**
 * Input for logon request
 */
export type LogonInput = {
  username: string;
  password: string;
  kulo?: boolean | undefined;
};

/**
 * Minimal user data from database query
 */
export type UserQueryResult = {
  userPkId: number;
  username: string;
  password: string;
  enabled: boolean;
};

/**
 * Minimal project data for owned projects query
 */
export type OwnedProjectQueryResult = {
  projectId: string;
};

Version 2 (latest)

import type { SqlClientType, ILogger } from 'cwc-backend-utils';
import type { CwcLoginType } from 'cwc-types';
import type { CwcAuthConfig } from '../config';

/**
 * Dependencies for auth factory functions
 */
export type AuthDependencies = {
  sqlClient: SqlClientType;
  config: CwcAuthConfig;
  logger: ILogger | undefined;
};

/**
 * JWT type returned in responses
 */
export type AuthJwtType = 'user' | 'temp' | undefined;

/**
 * Auth error codes for detailed error handling
 */
export type AuthErrorCode =
  | 'MISSING_CREDENTIALS'
  | 'INVALID_CREDENTIALS'  // Generic error for user enumeration protection
  | 'USER_NOT_FOUND'
  | 'USER_DISABLED'
  | 'INVALID_PASSWORD'
  | 'JWT_CREATION_FAILED'
  | 'MISSING_TOKEN'
  | 'INVALID_TOKEN'
  | 'TOKEN_EXPIRED'
  | 'SESSION_NOT_FOUND'
  | 'SESSION_REVOKED'
  | 'INTERNAL_ERROR';

/**
 * Result of authentication operation
 */
export type AuthenticateUserResult =
  | {
      success: true;
      jwt: string;
      userPkId: number;
      username: string;
    }
  | {
      success: false;
      errorCode: AuthErrorCode;
      errorDetail?: string | undefined;
    };

/**
 * Result of session invalidation
 */
export type InvalidateSessionResult =
  | { success: true }
  | {
      success: false;
      errorCode: AuthErrorCode;
      errorDetail?: string | undefined;
    };

/**
 * Result of session renewal
 */
export type RenewSessionResult =
  | {
      success: true;
      jwt: string;
    }
  | {
      success: false;
      errorCode: AuthErrorCode;
      errorDetail?: string | undefined;
    };

/**
 * Input for logon request
 */
export type LogonInput = {
  username: string;
  password: string;
  kulo?: boolean | undefined;
};

/**
 * Minimal user data from database query
 */
export type UserQueryResult = {
  userPkId: number;
  username: string;
  password: string;
  enabled: boolean;
  deviceId: string;
  loginType: CwcLoginType;
};

/**
 * Minimal project data for owned projects query
 */
export type OwnedProjectQueryResult = {
  projectId: string;
};

packages/cwc-auth/src/auth/createAuthenticateUser.ts

2 versions

Version 1

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.isDevelopment
          ? 'Username and password are required'
          : undefined,
      };
    }

    try {
      // Query user by username
      const userCommand = sqlClient.selectCommand({
        table: 'user',
        filters: { username },
        fields: ['userPkId', 'username', 'password', 'enabled'],
      });
      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.isDevelopment ? internalReason as 'USER_NOT_FOUND' | 'USER_DISABLED' | 'INVALID_PASSWORD' : 'INVALID_CREDENTIALS',
          errorDetail: config.isDevelopment
            ? 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.isDevelopment
            ? '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,
          username: user.username,
          kulo,
          ownedProjects,
        },
        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.isDevelopment
          ? error instanceof Error
            ? error.message
            : 'Unknown error'
          : undefined,
      };
    }
  };
}

Version 2 (latest)

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.isDevelopment
          ? '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.isDevelopment ? internalReason as 'USER_NOT_FOUND' | 'USER_DISABLED' | 'INVALID_PASSWORD' : 'INVALID_CREDENTIALS',
          errorDetail: config.isDevelopment
            ? 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.isDevelopment
            ? '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.isDevelopment
          ? error instanceof Error
            ? error.message
            : 'Unknown error'
          : undefined,
      };
    }
  };
}

packages/cwc-auth/src/auth/createInvalidateSession.ts

2 versions

Version 1

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.isDevelopment
          ? '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.isDevelopment
        ? (verifyResult.error === 'TOKEN_EXPIRED' ? 'TOKEN_EXPIRED' : 'INVALID_TOKEN')
        : 'INVALID_TOKEN';

      return {
        success: false,
        errorCode,
        errorDetail: config.isDevelopment
          ? `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.isDevelopment
            ? '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.isDevelopment
            ? '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.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.isDevelopment
          ? error instanceof Error
            ? error.message
            : 'Unknown error'
          : undefined,
      };
    }
  };
}

Version 2 (latest)

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.isDevelopment
          ? '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.isDevelopment
        ? (verifyResult.error === 'TOKEN_EXPIRED' ? 'TOKEN_EXPIRED' : 'INVALID_TOKEN')
        : 'INVALID_TOKEN';

      return {
        success: false,
        errorCode,
        errorDetail: config.isDevelopment
          ? `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.isDevelopment
            ? '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.isDevelopment
            ? '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.isDevelopment
          ? error instanceof Error
            ? error.message
            : 'Unknown error'
          : undefined,
      };
    }
  };
}

packages/cwc-auth/src/auth/createRenewSession.ts

2 versions

Version 1

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.isDevelopment
          ? '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.isDevelopment
        ? (verifyResult.error === 'TOKEN_EXPIRED' ? 'TOKEN_EXPIRED' : 'INVALID_TOKEN')
        : 'INVALID_TOKEN';

      return {
        success: false,
        errorCode,
        errorDetail: config.isDevelopment
          ? `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.isDevelopment
            ? '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.isDevelopment
            ? '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.isDevelopment
            ? 'Failed to create new session record'
            : undefined,
        };
      }

      // Create new JWT with fresh ownedProjects (preserve kulo flag)
      const expiresIn = (payload.kulo
        ? config.userJwtExpiresInKulo
        : config.userJwtExpiresIn) as StringValue;

      const newJwt = createUserJwt(
        {
          jti: newUserJwtId,
          sub: payload.sub,
          username: payload.username,
          kulo: payload.kulo,
          ownedProjects,
        },
        config.secrets.userJwtSecret,
        expiresIn
      );

      if (config.debugMode) {
        logger?.logInformation({
          userPkId: payload.sub,
          codeLocation,
          message: 'Session renewed successfully',
          value: {
            oldUserJwtId: payload.jti,
            newUserJwtId,
            username: payload.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.isDevelopment
          ? error instanceof Error
            ? error.message
            : 'Unknown error'
          : undefined,
      };
    }
  };
}

Version 2 (latest)

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.isDevelopment
          ? '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.isDevelopment
        ? (verifyResult.error === 'TOKEN_EXPIRED' ? 'TOKEN_EXPIRED' : 'INVALID_TOKEN')
        : 'INVALID_TOKEN';

      return {
        success: false,
        errorCode,
        errorDetail: config.isDevelopment
          ? `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.isDevelopment
            ? '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.isDevelopment
            ? '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.isDevelopment
            ? '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.isDevelopment
          ? error instanceof Error
            ? error.message
            : 'Unknown error'
          : undefined,
      };
    }
  };
}

packages/cwc-auth/src/jwt/createUserJwt.ts

2 versions

Version 1

import jwt, { type SignOptions } from 'jsonwebtoken';
import type { StringValue } from 'ms';
import type { UserJwtPayloadInput } from './jwt.types';

/**
 * Creates a signed user JWT using HS256 algorithm
 *
 * @param payload - The JWT payload (without iat/exp)
 * @param secret - HS256 secret for signing
 * @param expiresIn - JWT expiration time (e.g., '15m', '30d')
 * @returns Signed JWT string
 */
export function createUserJwt(
  payload: UserJwtPayloadInput,
  secret: string,
  expiresIn: StringValue
): string {
  const signOptions: SignOptions = {
    algorithm: 'HS256',
    expiresIn,
    jwtid: payload.jti,
    subject: String(payload.sub),
  };

  return jwt.sign(
    {
      username: payload.username,
      kulo: payload.kulo,
      ownedProjects: payload.ownedProjects,
    },
    secret,
    signOptions
  );
}

Version 2 (latest)

import jwt, { type SignOptions } from 'jsonwebtoken';
import type { StringValue } from 'ms';
import type { UserJwtPayloadInput } from './jwt.types';

/**
 * Creates a signed user JWT using HS256 algorithm
 *
 * @param payload - The JWT payload (without iat/exp)
 * @param secret - HS256 secret for signing
 * @param expiresIn - JWT expiration time (e.g., '15m', '30d')
 * @returns Signed JWT string
 */
export function createUserJwt(
  payload: UserJwtPayloadInput,
  secret: string,
  expiresIn: StringValue
): string {
  const signOptions: SignOptions = {
    algorithm: 'HS256',
    expiresIn,
    jwtid: payload.jti,
    subject: String(payload.sub),
  };

  return jwt.sign(
    {
      login: payload.login,
    },
    secret,
    signOptions
  );
}

packages/cwc-auth/src/jwt/jwt.types.ts

2 versions

Version 1

/**
 * User JWT payload structure
 * Contains claims for authenticated users
 */
export type UserJwtPayload = {
  // Standard JWT claims
  jti: string;        // JWT ID - userJwtId (UUID) references userJwt table
  sub: number;        // Subject - userPkId
  iat: number;        // Issued at (Unix timestamp)
  exp: number;        // Expiration (Unix timestamp)

  // Custom claims
  username: string;
  kulo: boolean;           // Keep-user-logged-on flag
  ownedProjects: string[]; // Array of projectId (natural keys) user owns
};

/**
 * Payload for creating a new user JWT (without iat/exp which are added by jsonwebtoken)
 */
export type UserJwtPayloadInput = Omit<UserJwtPayload, 'iat' | 'exp'>;

/**
 * Result of JWT verification
 */
export type VerifyUserJwtResult =
  | { success: true; payload: UserJwtPayload }
  | { success: false; error: JwtVerifyError };

/**
 * JWT verification error types
 */
export type JwtVerifyError =
  | 'MISSING_TOKEN'
  | 'INVALID_TOKEN'
  | 'TOKEN_EXPIRED'
  | 'INVALID_SIGNATURE'
  | 'MALFORMED_PAYLOAD';

Version 2 (latest)

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

/**
 * User JWT payload structure
 * Contains standard JWT claims plus CwcLoginClaims
 */
export type UserJwtPayload = {
  // Standard JWT claims
  jti: string; // JWT ID - userJwtId (UUID) references userJwt table
  sub: number; // Subject - userPkId
  iat: number; // Issued at (Unix timestamp)
  exp: number; // Expiration (Unix timestamp)

  // Custom claims
  login: CwcLoginClaims;
};

/**
 * Payload for creating a new user JWT (without iat/exp which are added by jsonwebtoken)
 */
export type UserJwtPayloadInput = Omit<UserJwtPayload, 'iat' | 'exp'>;

/**
 * Result of JWT verification
 */
export type VerifyUserJwtResult =
  | { success: true; payload: UserJwtPayload }
  | { success: false; error: JwtVerifyError };

/**
 * JWT verification error types
 */
export type JwtVerifyError =
  | 'MISSING_TOKEN'
  | 'INVALID_TOKEN'
  | 'TOKEN_EXPIRED'
  | 'INVALID_SIGNATURE'
  | 'MALFORMED_PAYLOAD';

packages/cwc-auth/src/jwt/verifyUserJwt.ts

2 versions

Version 1

import jwt, { JsonWebTokenError, TokenExpiredError } from 'jsonwebtoken';
import type { UserJwtPayload, VerifyUserJwtResult } from './jwt.types';

/**
 * Type guard to validate JWT payload has all required fields
 */
function isValidUserJwtPayload(payload: unknown): payload is UserJwtPayload {
  if (!payload || typeof payload !== 'object') {
    return false;
  }

  const p = payload as Record<string, unknown>;

  // Basic type checks
  if (
    typeof p['jti'] !== 'string' ||
    typeof p['sub'] !== 'string' || // JWT stores sub as string, we parse to number
    typeof p['iat'] !== 'number' ||
    typeof p['exp'] !== 'number' ||
    typeof p['username'] !== 'string' ||
    typeof p['kulo'] !== 'boolean' ||
    !Array.isArray(p['ownedProjects']) ||
    !p['ownedProjects'].every((item) => typeof item === 'string')
  ) {
    return false;
  }

  // SECURITY: Validate sub claim is a valid positive integer string
  // Prevents NaN and integer overflow attacks
  const subString = p['sub'] as string;
  const subNumber = parseInt(subString, 10);
  if (
    isNaN(subNumber) ||
    subNumber <= 0 ||
    subNumber > Number.MAX_SAFE_INTEGER ||
    String(subNumber) !== subString // Ensure no extra characters
  ) {
    return false;
  }

  return true;
}

/**
 * Verifies a user JWT and extracts the payload
 *
 * @param token - The JWT string to verify
 * @param secret - HS256 secret for verification
 * @returns VerifyUserJwtResult with success/payload or error
 */
export function verifyUserJwt(
  token: string | undefined,
  secret: string
): VerifyUserJwtResult {
  if (!token) {
    return { success: false, error: 'MISSING_TOKEN' };
  }

  try {
    const decoded = jwt.verify(token, secret, {
      algorithms: ['HS256'],
    });

    if (!isValidUserJwtPayload(decoded)) {
      return { success: false, error: 'MALFORMED_PAYLOAD' };
    }

    // Convert sub from string to number and construct payload explicitly
    const payload: UserJwtPayload = {
      jti: decoded.jti,
      sub: parseInt(decoded.sub as unknown as string, 10),
      iat: decoded.iat,
      exp: decoded.exp,
      username: decoded.username,
      kulo: decoded.kulo,
      ownedProjects: decoded.ownedProjects,
    };

    return { success: true, payload };
  } catch (error) {
    if (error instanceof TokenExpiredError) {
      return { success: false, error: 'TOKEN_EXPIRED' };
    }
    if (error instanceof JsonWebTokenError) {
      if (error.message.includes('signature')) {
        return { success: false, error: 'INVALID_SIGNATURE' };
      }
      return { success: false, error: 'INVALID_TOKEN' };
    }
    return { success: false, error: 'INVALID_TOKEN' };
  }
}

Version 2 (latest)

import jwt, { JsonWebTokenError, TokenExpiredError } from 'jsonwebtoken';
import type { CwcLoginClaims } from 'cwc-types';
import type { UserJwtPayload, VerifyUserJwtResult } from './jwt.types';

/**
 * Type guard to validate login claims object
 */
function isValidLoginClaims(login: unknown): login is CwcLoginClaims {
  if (!login || typeof login !== 'object') {
    return false;
  }

  const l = login as Record<string, unknown>;

  if (
    typeof l['username'] !== 'string' ||
    typeof l['deviceId'] !== 'string' ||
    typeof l['userJwtId'] !== 'string' ||
    typeof l['loginType'] !== 'string' ||
    typeof l['kulo'] !== 'boolean' ||
    typeof l['isGuestUser'] !== 'boolean' ||
    !Array.isArray(l['ownedProjects']) ||
    !l['ownedProjects'].every((item) => typeof item === 'string')
  ) {
    return false;
  }

  // Validate loginType is one of the allowed values
  if (!['cwc', 'facebook', 'google'].includes(l['loginType'] as string)) {
    return false;
  }

  return true;
}

/**
 * Type guard to validate JWT payload has all required fields
 */
function isValidUserJwtPayload(payload: unknown): payload is UserJwtPayload {
  if (!payload || typeof payload !== 'object') {
    return false;
  }

  const p = payload as Record<string, unknown>;

  // Check standard JWT claims
  if (
    typeof p['jti'] !== 'string' ||
    typeof p['sub'] !== 'string' || // JWT stores sub as string, we parse to number
    typeof p['iat'] !== 'number' ||
    typeof p['exp'] !== 'number'
  ) {
    return false;
  }

  // SECURITY: Validate sub claim is a valid positive integer string
  // Prevents NaN and integer overflow attacks
  const subString = p['sub'] as string;
  const subNumber = parseInt(subString, 10);
  if (
    isNaN(subNumber) ||
    subNumber <= 0 ||
    subNumber > Number.MAX_SAFE_INTEGER ||
    String(subNumber) !== subString // Ensure no extra characters
  ) {
    return false;
  }

  // Validate login claims object
  if (!isValidLoginClaims(p['login'])) {
    return false;
  }

  return true;
}

/**
 * Verifies a user JWT and extracts the payload
 *
 * @param token - The JWT string to verify
 * @param secret - HS256 secret for verification
 * @returns VerifyUserJwtResult with success/payload or error
 */
export function verifyUserJwt(
  token: string | undefined,
  secret: string
): VerifyUserJwtResult {
  if (!token) {
    return { success: false, error: 'MISSING_TOKEN' };
  }

  try {
    const decoded = jwt.verify(token, secret, {
      algorithms: ['HS256'],
    });

    if (!isValidUserJwtPayload(decoded)) {
      return { success: false, error: 'MALFORMED_PAYLOAD' };
    }

    // Convert sub from string to number and construct payload explicitly
    const payload: UserJwtPayload = {
      jti: decoded.jti,
      sub: parseInt(decoded.sub as unknown as string, 10),
      iat: decoded.iat,
      exp: decoded.exp,
      login: decoded.login,
    };

    return { success: true, payload };
  } catch (error) {
    if (error instanceof TokenExpiredError) {
      return { success: false, error: 'TOKEN_EXPIRED' };
    }
    if (error instanceof JsonWebTokenError) {
      if (error.message.includes('signature')) {
        return { success: false, error: 'INVALID_SIGNATURE' };
      }
      return { success: false, error: 'INVALID_TOKEN' };
    }
    return { success: false, error: 'INVALID_TOKEN' };
  }
}

packages/cwc-backend-utils/package.json

2 versions

Version 1

{
  "name": "cwc-backend-utils",
  "version": "1.0.0",
  "description": "Backend utilities for CWC microservices (Node.js only)",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [
    "cwc",
    "backend",
    "utilities",
    "node"
  ],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "@types/express": "^5.0.5",
    "@types/jsonwebtoken": "^9.0.10",
    "typescript": "^5.4.0"
  },
  "dependencies": {
    "axios": "^1.13.2",
    "cwc-types": "workspace:^",
    "dotenv": "^17.2.3",
    "express": "^5.1.0",
    "helmet": "^8.1.0",
    "jsonwebtoken": "^9.0.2",
    "rate-limiter-flexible": "^8.2.1",
    "uuid": "^13.0.0"
  }
}

Version 2 (latest)

{
  "name": "cwc-backend-utils",
  "version": "1.0.0",
  "description": "Backend utilities for CWC microservices (Node.js only)",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [
    "cwc",
    "backend",
    "utilities",
    "node"
  ],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "@types/express": "^5.0.5",
    "@types/jsonwebtoken": "^9.0.10",
    "typescript": "^5.4.0"
  },
  "dependencies": {
    "axios": "^1.13.2",
    "cwc-types": "workspace:^",
    "dotenv": "^17.2.3",
    "express": "^5.1.0",
    "helmet": "^8.1.0",
    "jsonwebtoken": "^9.0.2",
    "rate-limiter-flexible": "^8.2.1",
    "uuid": "^9.0.1"
  }
}

packages/cwc-types/src/entityTypes.ts

2 versions

Version 1

/**
 * CWC Database Entity Types
 *
 * This file contains TypeScript type definitions for all database entities.
 * Generated from the database schema in packages/cwc-database/schema-definition/
 *
 * Type Generation Conventions:
 * - All entity types prefixed with 'Cwc' to avoid naming conflicts
 * - Union types fully qualified with entity context to prevent ambiguity
 * - Use 'type' (not 'interface') for entity definitions
 * - Use string literal union types (not enums) for enum-like VARCHAR fields
 * - DATETIME columns mapped to string (ISO 8601 format)
 * - TINYINT columns mapped to boolean
 * - All fields required by default (even if DB allows NULL)
 * - Optional fields (?) only for business-critical reasons
 *
 * Working with Incomplete Data:
 * When working with partial entity data (e.g., during INSERT operations
 * where PkId doesn't exist yet, or multi-step processes), use TypeScript's
 * Partial<T> utility type:
 *
 * @example
 * // For INSERT operations (omit auto-generated fields)
 * type UserInsert = Omit<CwcUser, 'userPkId' | 'createdDate' | 'modifiedDate'>;
 *
 * // For partial updates
 * const partialUser: Partial<CwcUser> = { email: 'new@example.com' };
 *
 * // For specific operation requirements
 * type UserUpdate = Partial<UserInsert> & Pick<CwcUser, 'userPkId'>;
 */

// ============================================================================
// Union Types for Enum-like VARCHAR Fields
// ============================================================================

/**
 * Status values for abuse reports
 */
export type CwcAbuseReportStatus =
  | 'submitted'
  | 'investigation'
  | 'dismissed'
  | 'resolved'
  | 'retracted';

/**
 * Entity types that can be commented on
 * Note: Each entity using this type may have different allowed values
 */
export type CwcCommentEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

/**
 * Content types for coding session content blocks
 */
export type CwcCodingSessionContentType = 'prompt' | 'response' | 'note' | 'attachment';

/**
 * MIME types for coding session attachments
 */
export type CwcCodingSessionAttachmentMimeType = 'image/png' | 'image/jpg';

/**
 * Entity types that can be reported for inappropriate content
 * Note: May differ from comment entity types in the future
 */
export type CwcContentReportEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

/**
 * Status values for content reports
 */
export type CwcContentReportStatus =
  | 'submitted'
  | 'investigation'
  | 'dismissed'
  | 'resolved'
  | 'retracted';

/**
 * Error log severity/type levels
 */
export type CwcErrorLogType = 'error' | 'info' | 'warn' | 'debug';

/**
 * Service names for error logging
 */
export type CwcErrorLogServiceName =
  | 'cwc-auth'
  | 'cwc-api'
  | 'cwc-sql'
  | 'cwc-storage'
  | 'cwc-website'
  | 'cwc-admin-api';

/**
 * Feature flag type classification
 */
export type CwcFeatureFlagType = 'feature' | 'system';

/**
 * Platform targets for feature flags
 */
export type CwcFeatureFlagPlatform = 'all' | 'web' | 'android' | 'ios' | 'mobile';

/**
 * Service names for feature flag targeting
 */
export type CwcFeatureFlagServiceName =
  | 'all'
  | 'frontend'
  | 'backend'
  | 'cwc-app'
  | 'cwc-sql'
  | 'cwc-auth'
  | 'cwc-api'
  | 'cwc-admin-api'
  | 'cwc-dashboard';

/**
 * Value types for feature flag values
 */
export type CwcFeatureFlagValueType = 'boolean' | 'number' | 'string' | 'object';

/**
 * Login/authentication types
 * Shared by user and signupInfo entities
 */
export type CwcLoginType = 'cwc' | 'facebook' | 'google';

/**
 * Project type classifications
 */
export type CwcProjectType = 'web' | 'mobile' | 'backend' | 'ai';

/**
 * Reaction emoji names
 */
export type CwcReactionName = 'love' | 'funny' | 'sad' | 'wow' | 'thumbs-up';

/**
 * Entity types that can receive reactions
 * Note: May differ from comment/report entity types in the future
 */
export type CwcReactionEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

// ============================================================================
// Entity Types
// ============================================================================

/**
 * Abuse Report
 * Tracks user reports of abusive behavior or accounts
 */
export type CwcAbuseReport = {
  abuseReportPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  usernames: string;
  message: string;
  status: CwcAbuseReportStatus;
};

/**
 * Admin User
 * Administrative users for the dashboard
 */
export type CwcAdminUser = {
  adminUserPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  adminUsername: string;
  password: string;
};

/**
 * Admin User JWT
 * JWT validation/revocation for admin users
 * Contains only JWT ID for lookup; payload contains full user context
 */
export type CwcAdminUserJwt = {
  adminUserJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  adminUserJwtId: string;
};

/**
 * Coding Session
 * Individual coding sessions within a project
 * Stores metadata and reference to session data in cwc-storage
 */
export type CwcCodingSession = {
  codingSessionPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  description: string;
  published: boolean;
  sessionId: string;
  storageKey: string;
  startTimestamp: string;
  endTimestamp: string;
  gitBranch: string;
  model: string;
  messageCount: number;
  filesModifiedCount: number;
};

/**
 * Coding Session Attachment
 * Images and files attached to coding sessions
 */
export type CwcCodingSessionAttachment = {
  codingSessionAttachmentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  codingSessionPkId: number;
  filename: string;
  mimeType: CwcCodingSessionAttachmentMimeType;
  height: number;
  width: number;
};

/**
 * Coding Session Content
 * Content blocks (prompts, responses, notes, attachments) within a session
 * Uses displayIndex for rendering order of all content types
 * Polymorphic: text OR attachment based on contentType
 */
export type CwcCodingSessionContent = {
  codingSessionContentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  contentType: CwcCodingSessionContentType;
  codingSessionPkId: number;
  codingSessionAttachmentPkId?: number; // Optional: only present when contentType='attachment'
  displayIndex: number;
  text?: string; // Optional: NULL for pure attachment blocks, or optional caption for attachments
};

/**
 * Comment
 * User comments on various entities (polymorphic relationship)
 * Uses entityPkId + entityType pattern to reference any commentable entity
 */
export type CwcComment = {
  commentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectPkId: number;
  userPkId: number;
  entityPkId: number;
  entityType: CwcCommentEntityType;
  text: string;
};

/**
 * Content Report
 * User reports of inappropriate content (polymorphic relationship)
 */
export type CwcContentReport = {
  contentReportPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  entityPkId: number;
  entityType: CwcContentReportEntityType;
  message: string;
  status: CwcContentReportStatus;
};

/**
 * Email Verify
 * Email verification tracking (standalone, not tied to signup/reset)
 */
export type CwcEmailVerify = {
  emailVerifyPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  confirmationCode: string;
  email: string;
  deviceId: string;
  confirmed: boolean;
  emailVerificationId: string;
};

/**
 * Error Log
 * Centralized error logging for all microservices
 */
export type CwcErrorLog = {
  errorLogPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId?: number | undefined; // Optional: errors can occur without user context
  projectPkId?: number | undefined; // Optional: errors can occur without project context
  serviceName: CwcErrorLogServiceName;
  codeLocation: string;
  dismissed: boolean;
  errorType: CwcErrorLogType;
  errorMessage: string;
  error: string;
  stack: string;
  data: string;
  request: string;
};

/**
 * Feature Flag
 * Runtime feature toggles and configuration
 */
export type CwcFeatureFlag = {
  featureFlagPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  featureFlagType: CwcFeatureFlagType;
  featureFlagId: string;
  valueType: CwcFeatureFlagValueType;
  value: string;
  description: string;
  platform: CwcFeatureFlagPlatform;
  serviceName: CwcFeatureFlagServiceName;
};

/**
 * Password Reset Info
 * Tracks password reset process state
 * Stores denormalized user data collected during the reset flow
 */
export type CwcPasswordResetInfo = {
  passwordResetInfoPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  username: string;
  password?: string; // Optional: not set until user provides new password
  email: string;
  emailVerificationId: string;
  emailConfirmed: boolean;
  deviceId: string;
  passwordResetAttempts: number;
};

/**
 * Project
 * User projects that contain coding sessions
 */
export type CwcProject = {
  projectPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectId: string;
  projectSessionFolder: string;
  projectType: CwcProjectType;
  userPkId: number;
};

/**
 * Reaction
 * User reactions (emoji-style) to various entities
 */
export type CwcReaction = {
  reactionPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectPkId: number;
  userPkId: number;
  entityPkId: number;
  entityType: CwcReactionEntityType;
  reactionName: CwcReactionName;
};

/**
 * Signup Info
 * Tracks signup process state
 * Stores denormalized user data collected during the signup flow
 */
export type CwcSignupInfo = {
  signupInfoPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  loginType: CwcLoginType;
  userPkId?: number; // Optional: not set until signup completes
  username: string;
  password?: string; // Optional: NULL for OAuth signups or until provided
  email: string;
  emailVerificationId: string;
  emailConfirmed: boolean;
  deviceId: string;
  signupAttempts: number;
};

/**
 * Temp JWT
 * JWT validation/revocation for temporary multi-step processes
 * Contains only JWT ID for lookup; payload contains process context
 */
export type CwcTempJwt = {
  tempJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  tempJwtId: string;
};

/**
 * User
 * Primary user accounts
 */
export type CwcUser = {
  userPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  username: string;
  loginType: CwcLoginType;
  loginDate: string;
  password?: string; // Optional: NULL for OAuth users
  email: string;
  emailConfirmed: boolean;
  deviceId: string;
  otpSecret?: string; // Optional: only present if 2FA enabled
  otpValidated: boolean;
};

/**
 * User JWT
 * JWT validation/revocation for regular users
 * Contains only JWT ID for lookup; payload contains full user context
 */
export type CwcUserJwt = {
  userJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userJwtId: string;
};

Version 2 (latest)

/**
 * CWC Database Entity Types
 *
 * This file contains TypeScript type definitions for all database entities.
 * Generated from the database schema in packages/cwc-database/schema-definition/
 *
 * Type Generation Conventions:
 * - All entity types prefixed with 'Cwc' to avoid naming conflicts
 * - Union types fully qualified with entity context to prevent ambiguity
 * - Use 'type' (not 'interface') for entity definitions
 * - Use string literal union types (not enums) for enum-like VARCHAR fields
 * - DATETIME columns mapped to string (ISO 8601 format)
 * - TINYINT columns mapped to boolean
 * - All fields required by default (even if DB allows NULL)
 * - Optional fields (?) only for business-critical reasons
 *
 * Working with Incomplete Data:
 * When working with partial entity data (e.g., during INSERT operations
 * where PkId doesn't exist yet, or multi-step processes), use TypeScript's
 * Partial<T> utility type:
 *
 * @example
 * // For INSERT operations (omit auto-generated fields)
 * type UserInsert = Omit<CwcUser, 'userPkId' | 'createdDate' | 'modifiedDate'>;
 *
 * // For partial updates
 * const partialUser: Partial<CwcUser> = { email: 'new@example.com' };
 *
 * // For specific operation requirements
 * type UserUpdate = Partial<UserInsert> & Pick<CwcUser, 'userPkId'>;
 */

// ============================================================================
// Union Types for Enum-like VARCHAR Fields
// ============================================================================

/**
 * Status values for abuse reports
 */
export type CwcAbuseReportStatus =
  | 'submitted'
  | 'investigation'
  | 'dismissed'
  | 'resolved'
  | 'retracted';

/**
 * Entity types that can be commented on
 * Note: Each entity using this type may have different allowed values
 */
export type CwcCommentEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

/**
 * Content types for coding session content blocks
 */
export type CwcCodingSessionContentType = 'prompt' | 'response' | 'note' | 'attachment';

/**
 * MIME types for coding session attachments
 */
export type CwcCodingSessionAttachmentMimeType = 'image/png' | 'image/jpg';

/**
 * Entity types that can be reported for inappropriate content
 * Note: May differ from comment entity types in the future
 */
export type CwcContentReportEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

/**
 * Status values for content reports
 */
export type CwcContentReportStatus =
  | 'submitted'
  | 'investigation'
  | 'dismissed'
  | 'resolved'
  | 'retracted';

/**
 * Error log severity/type levels
 */
export type CwcErrorLogType = 'error' | 'info' | 'warn' | 'debug';

/**
 * Service names for error logging
 */
export type CwcErrorLogServiceName =
  | 'cwc-auth'
  | 'cwc-api'
  | 'cwc-sql'
  | 'cwc-storage'
  | 'cwc-website'
  | 'cwc-admin-api';

/**
 * Feature flag type classification
 */
export type CwcFeatureFlagType = 'feature' | 'system';

/**
 * Platform targets for feature flags
 */
export type CwcFeatureFlagPlatform = 'all' | 'web' | 'android' | 'ios' | 'mobile';

/**
 * Service names for feature flag targeting
 */
export type CwcFeatureFlagServiceName =
  | 'all'
  | 'frontend'
  | 'backend'
  | 'cwc-app'
  | 'cwc-sql'
  | 'cwc-auth'
  | 'cwc-api'
  | 'cwc-admin-api'
  | 'cwc-dashboard';

/**
 * Value types for feature flag values
 */
export type CwcFeatureFlagValueType = 'boolean' | 'number' | 'string' | 'object';

/**
 * Login/authentication types
 * Shared by user and signupInfo entities
 */
export type CwcLoginType = 'cwc' | 'facebook' | 'google';

/**
 * JWT Claims for authenticated users
 * Embedded in UserJwtPayload.login custom claim
 * Used by cwc-auth (token generation) and cwc-api (authorization)
 */
export type CwcLoginClaims = {
  username: string;
  deviceId: string;
  userJwtId: string;
  loginType: CwcLoginType;
  kulo: boolean;
  ownedProjects: string[];
  isGuestUser: boolean;
};

/**
 * Frontend session state
 * Extends CwcLoginClaims with client-side session management fields
 * Used by cwc-website for maintaining login state
 */
export type CwcLogin = CwcLoginClaims & {
  autoLogonAttempted: boolean;
  authToken?: string; // undefined for guest users
};

/**
 * Project type classifications
 */
export type CwcProjectType = 'web' | 'mobile' | 'backend' | 'ai';

/**
 * Reaction emoji names
 */
export type CwcReactionName = 'love' | 'funny' | 'sad' | 'wow' | 'thumbs-up';

/**
 * Entity types that can receive reactions
 * Note: May differ from comment/report entity types in the future
 */
export type CwcReactionEntityType =
  | 'project'
  | 'codingSession'
  | 'codingSessionContent'
  | 'codingSessionAttachment'
  | 'comment';

// ============================================================================
// Entity Types
// ============================================================================

/**
 * Abuse Report
 * Tracks user reports of abusive behavior or accounts
 */
export type CwcAbuseReport = {
  abuseReportPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  usernames: string;
  message: string;
  status: CwcAbuseReportStatus;
};

/**
 * Admin User
 * Administrative users for the dashboard
 */
export type CwcAdminUser = {
  adminUserPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  adminUsername: string;
  password: string;
};

/**
 * Admin User JWT
 * JWT validation/revocation for admin users
 * Contains only JWT ID for lookup; payload contains full user context
 */
export type CwcAdminUserJwt = {
  adminUserJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  adminUserJwtId: string;
};

/**
 * Coding Session
 * Individual coding sessions within a project
 * Stores metadata and reference to session data in cwc-storage
 */
export type CwcCodingSession = {
  codingSessionPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  description: string;
  published: boolean;
  sessionId: string;
  storageKey: string;
  startTimestamp: string;
  endTimestamp: string;
  gitBranch: string;
  model: string;
  messageCount: number;
  filesModifiedCount: number;
};

/**
 * Coding Session Attachment
 * Images and files attached to coding sessions
 */
export type CwcCodingSessionAttachment = {
  codingSessionAttachmentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  codingSessionPkId: number;
  filename: string;
  mimeType: CwcCodingSessionAttachmentMimeType;
  height: number;
  width: number;
};

/**
 * Coding Session Content
 * Content blocks (prompts, responses, notes, attachments) within a session
 * Uses displayIndex for rendering order of all content types
 * Polymorphic: text OR attachment based on contentType
 */
export type CwcCodingSessionContent = {
  codingSessionContentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  contentType: CwcCodingSessionContentType;
  codingSessionPkId: number;
  codingSessionAttachmentPkId?: number; // Optional: only present when contentType='attachment'
  displayIndex: number;
  text?: string; // Optional: NULL for pure attachment blocks, or optional caption for attachments
};

/**
 * Comment
 * User comments on various entities (polymorphic relationship)
 * Uses entityPkId + entityType pattern to reference any commentable entity
 */
export type CwcComment = {
  commentPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectPkId: number;
  userPkId: number;
  entityPkId: number;
  entityType: CwcCommentEntityType;
  text: string;
};

/**
 * Content Report
 * User reports of inappropriate content (polymorphic relationship)
 */
export type CwcContentReport = {
  contentReportPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  projectPkId: number;
  entityPkId: number;
  entityType: CwcContentReportEntityType;
  message: string;
  status: CwcContentReportStatus;
};

/**
 * Email Verify
 * Email verification tracking (standalone, not tied to signup/reset)
 */
export type CwcEmailVerify = {
  emailVerifyPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  confirmationCode: string;
  email: string;
  deviceId: string;
  confirmed: boolean;
  emailVerificationId: string;
};

/**
 * Error Log
 * Centralized error logging for all microservices
 */
export type CwcErrorLog = {
  errorLogPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId?: number | undefined; // Optional: errors can occur without user context
  projectPkId?: number | undefined; // Optional: errors can occur without project context
  serviceName: CwcErrorLogServiceName;
  codeLocation: string;
  dismissed: boolean;
  errorType: CwcErrorLogType;
  errorMessage: string;
  error: string;
  stack: string;
  data: string;
  request: string;
};

/**
 * Feature Flag
 * Runtime feature toggles and configuration
 */
export type CwcFeatureFlag = {
  featureFlagPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  featureFlagType: CwcFeatureFlagType;
  featureFlagId: string;
  valueType: CwcFeatureFlagValueType;
  value: string;
  description: string;
  platform: CwcFeatureFlagPlatform;
  serviceName: CwcFeatureFlagServiceName;
};

/**
 * Password Reset Info
 * Tracks password reset process state
 * Stores denormalized user data collected during the reset flow
 */
export type CwcPasswordResetInfo = {
  passwordResetInfoPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userPkId: number;
  username: string;
  password?: string; // Optional: not set until user provides new password
  email: string;
  emailVerificationId: string;
  emailConfirmed: boolean;
  deviceId: string;
  passwordResetAttempts: number;
};

/**
 * Project
 * User projects that contain coding sessions
 */
export type CwcProject = {
  projectPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectId: string;
  projectSessionFolder: string;
  projectType: CwcProjectType;
  userPkId: number;
};

/**
 * Reaction
 * User reactions (emoji-style) to various entities
 */
export type CwcReaction = {
  reactionPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  projectPkId: number;
  userPkId: number;
  entityPkId: number;
  entityType: CwcReactionEntityType;
  reactionName: CwcReactionName;
};

/**
 * Signup Info
 * Tracks signup process state
 * Stores denormalized user data collected during the signup flow
 */
export type CwcSignupInfo = {
  signupInfoPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  loginType: CwcLoginType;
  userPkId?: number; // Optional: not set until signup completes
  username: string;
  password?: string; // Optional: NULL for OAuth signups or until provided
  email: string;
  emailVerificationId: string;
  emailConfirmed: boolean;
  deviceId: string;
  signupAttempts: number;
};

/**
 * Temp JWT
 * JWT validation/revocation for temporary multi-step processes
 * Contains only JWT ID for lookup; payload contains process context
 */
export type CwcTempJwt = {
  tempJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  tempJwtId: string;
};

/**
 * User
 * Primary user accounts
 */
export type CwcUser = {
  userPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  username: string;
  loginType: CwcLoginType;
  loginDate: string;
  password?: string; // Optional: NULL for OAuth users
  email: string;
  emailConfirmed: boolean;
  deviceId: string;
  otpSecret?: string; // Optional: only present if 2FA enabled
  otpValidated: boolean;
};

/**
 * User JWT
 * JWT validation/revocation for regular users
 * Contains only JWT ID for lookup; payload contains full user context
 */
export type CwcUserJwt = {
  userJwtPkId: number;
  enabled: boolean;
  createdDate: string;
  modifiedDate: string;
  userJwtId: string;
};

Session 16: login user types

Session 16: login user types

CwcUser vs CwcLogin: Architectural Analysis

Terminology

Observations and Questions

1. Duplicate username in CwcLogin

2. Redundancy between JWT claims and CwcLogin

3. Fields in CwcLogin that seem session-management specific

4. CwcUser includes loginDate

5. Guest user representation

Point 3: Shared vs Separate Types for JWT Claims and Frontend State

The Problem with a Single Shared Type

Option A: Separate Types (Recommended)

Option B: Extended Type Pattern

Refined Option B

One Question on Guest State

Point 4: CwcUser includes loginDate

Point 5: Guest user representation

Summary of Agreed Design Decisions

Plan: CwcUser and CwcLogin Type Architecture

Summary

Design Decisions (from discussion)

Implementation Steps

Step 1: Add CwcLoginClaims to cwc-types

Step 2: Add CwcLogin to cwc-types

Step 3: Export new types from cwc-types index

Step 4: Update UserJwtPayload in cwc-auth

Step 5: Update createUserJwt function

Step 6: Update verifyUserJwt function

Step 7: Update createAuthenticateUser

Step 8: Update createRenewSession

Step 9: Update JWT tests

Step 10: Update cwc-auth CLAUDE.md

Step 11: Update root CLAUDE.md

Step 12: Run typecheck and tests

Files to Modify

Type Definitions Summary

Guest User Pattern (Frontend Reference)

Step 7: Update createAuthenticateUser

Step 8: Update createRenewSession

Files to Modify

Guest User Pattern (Frontend Reference)

cwc-api Usage Note

Implementation Complete

Session 16: login user types

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

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

1. Duplicate `username` in CwcLogin

4. CwcUser includes `loginDate`

LogonApiV1 (`/auth/v1`)

ServiceApiV1 (`/auth/v1`)

LogonApiV1 (`/auth/v1`)

ServiceApiV1 (`/auth/v1`)