@benefi/auth 1.0.4 → 1.0.5

package/README.md

@@ -0,0 +1,171 @@
+@benefi/auth
+============
+
+**Typed JWT verifier with AWS Secrets Manager rotation support.**
+
+This package provides a small helper around `jsonwebtoken` and AWS Secrets Manager to verify JWTs that are signed with a secret stored in Secrets Manager, with built‑in support for secret rotation (tries `AWSCURRENT` first, then `AWSPREVIOUS`) and structured error codes.
+
+### Installation
+
+```bash
+npm install @benefi/auth
+# or
+yarn add @benefi/auth
+```
+
+### When to use this package
+
+- **You store your JWT secret in AWS Secrets Manager.**
+- **You rotate the secret using version stages (`AWSCURRENT` / `AWSPREVIOUS`).**
+- **You want a simple verifier function that returns typed success/error results instead of throwing.**
+
+### Quick start
+
+```ts
+import { createTokenVerifier } from "@benefi/auth";
+
+// Option 1: pass a Secrets Manager secret ID string
+const verifyToken = createTokenVerifier("my-jwt-secret-id");
+
+// Option 2: pass a config object
+// const verifyToken = createTokenVerifier({
+//   secretId: "my-jwt-secret-id",
+//   region: "us-east-1", // optional, defaults to us-east-1
+// });
+
+const result = await verifyToken(tokenFromRequest);
+
+if (!result.success) {
+  // Use result.error.code to decide response status / message
+  // e.g. TOKEN_REQUIRED, TOKEN_EXPIRED, INVALID_TOKEN, SECRET_FETCH_FAILURE
+  console.error(result.error);
+  // return res.status(401).json({ error: result.error });
+} else {
+  // Decoded JWT payload with a stable shape
+  const { customerId, iat, exp } = result.data;
+  // Attach to request context, etc.
+  // req.customerId = customerId;
+}
+```
+
+### API
+
+#### `createTokenVerifier(secretOrConfig: SecretInput): (token: string) => Promise<VerifyResult>`
+
+Creates an async verifier function that you can call with a JWT string.
+
+- **`secretOrConfig`** (`SecretInput`)
+  - `string`: treated as an AWS Secrets Manager `SecretId`, region defaults to `us-east-1`.
+  - `{ secretId: string; region?: string }`: explicitly configure the secret id and AWS region.
+- **Return value**: an async function `verify(token: string): Promise<VerifyResult>`.
+
+The returned `verify` function:
+
+1. Validates that `token` is a non‑empty string.
+2. Fetches the secret from AWS Secrets Manager:
+   - First with version stage `AWSCURRENT`.
+   - If verification fails for any reason other than `TokenExpiredError`, retries with `AWSPREVIOUS`.
+3. Verifies the token using `jsonwebtoken`.
+4. Maps the decoded payload into a stable `DecodedJwt` shape:
+   - `customerId: string`
+   - `iat: number`
+   - `exp: number`
+5. Returns a typed `VerifyResult` instead of throwing.
+
+### Types
+
+These types are re‑exported from the main entry point:
+
+- **`SecretInput`**
+
+  ```ts
+  type JwtSecretConfig = {
+    secretId: string;
+    region?: string;
+  };
+
+  type SecretInput = string | JwtSecretConfig;
+  ```
+
+- **`DecodedJwt`**
+
+  ```ts
+  type DecodedJwt = {
+    customerId: string;
+    iat: number;
+    exp: number;
+  };
+  ```
+
+- **`ErrorCode`**
+
+  ```ts
+  type ErrorCode =
+    | "TOKEN_REQUIRED"
+    | "TOKEN_EXPIRED"
+    | "INVALID_TOKEN"
+    | "SECRET_FETCH_FAILURE";
+  ```
+
+- **`VerifySuccess`**
+
+  ```ts
+  type VerifySuccess = {
+    success: true;
+    data: DecodedJwt;
+    token: string;
+  };
+  ```
+
+- **`VerifyError`**
+
+  ```ts
+  type VerifyError = {
+    success: false;
+    error: {
+      code: ErrorCode;
+      message: string;
+    };
+  };
+  ```
+
+- **`VerifyResult`**
+
+  ```ts
+  type VerifyResult = VerifySuccess | VerifyError;
+  ```
+
+You can also import `ERROR_CODES` for convenience:
+
+```ts
+import { ERROR_CODES } from "@benefi/auth";
+
+if (!result.success && result.error.code === ERROR_CODES.TOKEN_EXPIRED) {
+  // handle expired token branch
+}
+```
+
+### AWS configuration
+
+This package uses `@aws-sdk/client-secrets-manager` under the hood. Make sure your environment is configured so the AWS SDK can authenticate:
+
+- **Environment variables** (e.g. `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`), or
+- **Instance/role credentials** (e.g. EC2 instance profile, ECS task role, Lambda execution role).
+
+If no region is provided in `JwtSecretConfig`, the package defaults to `"us-east-1"` (`DEFAULT_AWS_REGION`).
+
+### Error handling
+
+The verifier never throws for expected validation failures; instead it returns a `VerifyError`:
+
+- **`TOKEN_REQUIRED`** – token is missing, empty, or not a string.
+- **`TOKEN_EXPIRED`** – `jsonwebtoken` reported `TokenExpiredError` while verifying with the current secret.
+- **`INVALID_TOKEN`** – verification failed with both current and previous secrets (bad token, bad signature, wrong algorithm, etc.).
+- **`SECRET_FETCH_FAILURE`** – issues talking to Secrets Manager (e.g. permissions, missing secret, invalid response). The error message will contain the underlying AWS error when available.
+
+Use these codes to decide what HTTP status code and response body to send from your API.
+
+### License
+
+MIT
+

package/dist/src/constants.d.ts

@@ -6,5 +6,5 @@ export declare const ERROR_CODES: {
     readonly TOKEN_REQUIRED: "TOKEN_REQUIRED";
     readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
     readonly INVALID_TOKEN: "INVALID_TOKEN";
-    readonly SECRET_ERROR: "SECRET_ERROR";
+    readonly SECRET_FETCH_FAILURE: "SECRET_FETCH_FAILURE";
 };

package/dist/src/constants.js

@@ -9,5 +9,5 @@ exports.ERROR_CODES = {
     TOKEN_REQUIRED: "TOKEN_REQUIRED",
     TOKEN_EXPIRED: "TOKEN_EXPIRED",
     INVALID_TOKEN: "INVALID_TOKEN",
-    SECRET_ERROR: "SECRET_ERROR",
+    SECRET_FETCH_FAILURE: "SECRET_FETCH_FAILURE",
 };

package/dist/src/types.d.ts

@@ -9,7 +9,7 @@ export type DecodedJwt = {
     exp: number;
 };
 /** Error code returned when verification fails. */
-export type ErrorCode = "TOKEN_REQUIRED" | "TOKEN_EXPIRED" | "INVALID_TOKEN" | "SECRET_ERROR";
+export type ErrorCode = "TOKEN_REQUIRED" | "TOKEN_EXPIRED" | "INVALID_TOKEN" | "SECRET_FETCH_FAILURE";
 /** Success result: decoded payload + original token. */
 export type VerifySuccess = {
     success: true;

package/dist/src/verify.js

@@ -51,7 +51,7 @@ function createTokenVerifier(secretOrConfig) {
             return {
                 success: false,
                 error: {
-                    code: isAwsError ? "SECRET_ERROR" : "INVALID_TOKEN",
+                    code: isAwsError ? "SECRET_FETCH_FAILURE" : "INVALID_TOKEN",
                     message: isAwsError
                         ? (err instanceof Error ? err.message : "Failed to fetch secret")
                         : constants_1.TOKEN_INVALID_MESSAGE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benefi/auth",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/src/constants.ts

@@ -8,5 +8,5 @@ export const ERROR_CODES = {
   TOKEN_REQUIRED: "TOKEN_REQUIRED",
   TOKEN_EXPIRED: "TOKEN_EXPIRED",
   INVALID_TOKEN: "INVALID_TOKEN",
-  SECRET_ERROR: "SECRET_ERROR",
+  SECRET_FETCH_FAILURE: "SECRET_FETCH_FAILURE",
 } as const;

package/src/types.ts

@@ -18,7 +18,7 @@ export type ErrorCode =
   | "TOKEN_REQUIRED"
   | "TOKEN_EXPIRED"
   | "INVALID_TOKEN"
-  | "SECRET_ERROR";
+  | "SECRET_FETCH_FAILURE";
 
 /** Success result: decoded payload + original token. */
 export type VerifySuccess = {

package/src/verify.ts

@@ -60,7 +60,7 @@ export function createTokenVerifier(secretOrConfig: SecretInput) {
       return {
         success: false,
         error: {
-          code: isAwsError ? "SECRET_ERROR" : "INVALID_TOKEN",
+          code: isAwsError ? "SECRET_FETCH_FAILURE" : "INVALID_TOKEN",
           message: isAwsError
             ? (err instanceof Error ? err.message : "Failed to fetch secret")
             : TOKEN_INVALID_MESSAGE,