@occupop/lib-auth 4.0.0 → 4.1.1

package/README.md

@@ -27,6 +27,20 @@ ENV variables required
 JWT_SECRET=randomTokenProvidedByAuthService
 ```
 
+## Compatibility
+
+- **Node:** an ES module package (`"type": "module"`), loadable with `import` and with `require()`.
+  `require()` of an ES module needs `require(esm)`, which is on by default since Node 20.19 and
+  22.12; Node 22 and 24 are the versions tested. Since 4.1.0 the package takes `jsonwebtoken`, a
+  CommonJS module, through its default export, so it loads in Node. 4.0.0 and earlier loaded only
+  under Bun: Node failed with "Named export 'verify' not found".
+- **Bun:** loads with `import`, as before.
+- **Peers:** `@occupop/lib-container` `^4.0.1`, the first 4.x version that re-exports awilix's
+  `asValue`, which this package imports; `typescript` `^5.6.3 || ^6.0.0`.
+
+`bun run dist` ends with `bun run test:node`, which loads the built `dist/` with Node through both
+`import()` and `require()`.
+
 ## Register
 
 ```typescript
@@ -118,6 +132,11 @@ await httpServer.listen(httpPort, () => {
 // ...
 ```
 
+The middleware attaches the request-scoped container as `req.container`, then calls `next()`. If
+building the context fails (for example, a request carries a token while `JWT_SECRET` is not set),
+it calls `next(error)` instead, and Express's error handling takes over. Before 4.1.0 it never
+called `next()`, so a request passing through it hung.
+
 ```typescript
 // app/router.ts
 export function makeAppRouter({ httpRouter }: Deps) {
@@ -144,5 +163,28 @@ export function makeGetJobsUseCase({ authUser, jobService }: Deps) {
 }
 ```
 
+## Signing a token for another service
+
+`signAuthUserToken(authUser)` signs a user as a bearer token that another service verifies with
+the same `JWT_SECRET`, for example to call the GraphQL gateway on that user's behalf:
 
+```typescript
+import { signAuthUserToken } from '@occupop/lib-auth'
+
+const token = signAuthUserToken(authUser) // a string, or null when authUser is null
+const response = await fetch(gatewayUrl, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+  body: JSON.stringify({ query }),
+})
+```
 
+- HS256 with `JWT_SECRET`, read when the function is called. If it is not set, the function throws
+  `'Env var JWT_SECRET not set?'`, as verification does.
+- The payload is signed as given. A stored user that carries `iat` and `exp` keeps both; when it
+  has no `iat`, jsonwebtoken adds the signing time. No expiry, issuer or audience is added, so a
+  user without `exp` gives a token that does not expire.
+- `null` in, `null` out.
+- The token is identical to the one `@occupop/lib-context` 2.0.1's `makeGetAuthUserToken`
+  produces for the same user, secret and time. `src/index_test.ts` checks this against tokens
+  recorded from lib-context (`src/auth-user-token-vectors.json`).

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { IncomingMessage } from 'node:http';
+import type { IncomingMessage, ServerResponse } from 'node:http';
 import { type AwilixContainer } from '@occupop/lib-container';
 type Request = IncomingMessage & {
     container?: AwilixContainer;
@@ -8,9 +8,24 @@ export type AuthUser = {
     readonly hiringCompanyUuid?: string;
     readonly recruitmentAgencyUuid?: string;
     readonly sysAdmin?: boolean;
+    readonly sysAdminEmail?: string;
     readonly isAdmin?: boolean;
     readonly isSuperAdmin?: boolean;
+    readonly permissions?: Permission;
 };
+export interface Permission {
+    isSuperAdmin: boolean;
+    isAdmin: boolean;
+    candidates: boolean;
+    favorites: boolean;
+    recruiters: boolean;
+    formsDocuments: boolean;
+    contracts: boolean;
+    jobRequisition: boolean;
+    jobRequisitionCreate: boolean;
+    jobsCreate: boolean;
+    jobsPublish: boolean;
+}
 export type ScopedUser = {
     readonly userUuid?: undefined;
     readonly [entityUuid: string]: {
@@ -19,6 +34,13 @@ export type ScopedUser = {
 };
 export declare function getAuthUser(req: Request): AuthUser | null;
 export declare function getScopedUser(req: Request): ScopedUser | null;
+/**
+ * Signs `authUser` with `JWT_SECRET` (HS256), for calling another service on the user's behalf.
+ * The payload is signed as given: an `iat` or `exp` it carries is kept, jsonwebtoken adds `iat`
+ * only when it has none, and no expiry, issuer or audience is added. The token is the one
+ * `@occupop/lib-context` 2.0.1's `makeGetAuthUserToken` produces. Returns `null` for no user.
+ */
+export declare function signAuthUserToken(authUser: AuthUser | null): string | null;
 export declare function makeAuthContextValueFunction<IContainer extends AwilixContainer>({ container }: {
     container: IContainer;
 }): ({ req }: {
@@ -26,7 +48,11 @@ export declare function makeAuthContextValueFunction<IContainer extends AwilixCo
 }) => Promise<{
     container: AwilixContainer<any>;
 }>;
+/**
+ * Express middleware: attaches the request-scoped container as `req.container`, then calls
+ * `next()`. If building the context throws, it calls `next(error)` instead.
+ */
 export declare function makeAuthContextMiddleware<IContainer extends AwilixContainer>({ container, }: {
     container: IContainer;
-}): (req: Request) => Promise<void>;
+}): (req: Request, res: ServerResponse, next: (error?: unknown) => void) => Promise<void>;
 export {};

package/dist/index.js

@@ -1,5 +1,5 @@
 import { asValue } from '@occupop/lib-container';
-import { verify } from 'jsonwebtoken';
+import jwt from 'jsonwebtoken';
 function getToken(req) {
     return req.headers.authorization?.replace(/^Bearer /, '');
 }
@@ -9,7 +9,7 @@ function checkToken(token) {
     if (!process.env.JWT_SECRET)
         throw 'Env var JWT_SECRET not set?';
     try {
-        return verify(token, process.env.JWT_SECRET);
+        return jwt.verify(token, process.env.JWT_SECRET);
     }
     catch (e) {
         return null;
@@ -31,6 +31,19 @@ export function getScopedUser(req) {
         return user;
     return null;
 }
+/**
+ * Signs `authUser` with `JWT_SECRET` (HS256), for calling another service on the user's behalf.
+ * The payload is signed as given: an `iat` or `exp` it carries is kept, jsonwebtoken adds `iat`
+ * only when it has none, and no expiry, issuer or audience is added. The token is the one
+ * `@occupop/lib-context` 2.0.1's `makeGetAuthUserToken` produces. Returns `null` for no user.
+ */
+export function signAuthUserToken(authUser) {
+    if (!authUser)
+        return null;
+    if (!process.env.JWT_SECRET)
+        throw 'Env var JWT_SECRET not set?';
+    return jwt.sign(authUser, process.env.JWT_SECRET);
+}
 export function makeAuthContextValueFunction({ container }) {
     return async ({ req }) => {
         const authUser = getAuthUser(req);
@@ -43,10 +56,22 @@ export function makeAuthContextValueFunction({ container }) {
         return { container: scopedContainer };
     };
 }
+/**
+ * Express middleware: attaches the request-scoped container as `req.container`, then calls
+ * `next()`. If building the context throws, it calls `next(error)` instead.
+ */
 export function makeAuthContextMiddleware({ container, }) {
-    return async (req) => {
-        const authContextValueFunction = makeAuthContextValueFunction({ container });
-        const contextValue = await authContextValueFunction({ req });
-        req.container = contextValue.container;
+    return async (req, res, next) => {
+        try {
+            const authContextValueFunction = makeAuthContextValueFunction({
+                container,
+            });
+            const contextValue = await authContextValueFunction({ req });
+            req.container = contextValue.container;
+        }
+        catch (error) {
+            return next(error);
+        }
+        next();
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@occupop/lib-auth",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "main": "dist/index.js",
   "module": "index.ts",
   "description": "...",
@@ -12,7 +12,8 @@
     "test": "bun test",
     "cover": "bun test --coverage",
     "lint": "biome lint",
-    "dist": "bun lint && bun cover && rm -fr dist && tsc"
+    "test:node": "node test/node-load.mjs",
+    "dist": "bun lint && bun cover && rm -fr dist && tsc && bun run test:node"
   },
   "type": "module",
   "types": "dist/index.d.ts",
@@ -20,11 +21,12 @@
     "jsonwebtoken": "^9.0.2"
   },
   "peerDependencies": {
-    "@occupop/lib-container": "^4.0.0",
-    "typescript": "^5.6.3"
+    "@occupop/lib-container": "^4.0.1",
+    "typescript": "^5.6.3 || ^6.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
+    "@occupop/lib-container": "^4.0.1",
     "@types/bun": "latest",
     "@types/jsonwebtoken": "^9.0.7"
   }