@versini/auth-common 4.4.0 → 4.5.1

package/README.md

@@ -1,3 +1,62 @@
 # @versini/auth-common
 
-This package provides common utilities and constants for both the client and server side of the authentication system.
+Shared low-level building blocks (constants, token helpers, PKCE utilities, session helpers) used by `@versini/auth-provider` and any backend or frontend integration that needs to validate / manipulate auth artifacts.
+
+## Install
+
+```bash
+pnpm add @versini/auth-common
+```
+
+Peer dependency expectations: none (pure ESM, no React required).
+
+## Exports Overview
+
+All exports are re-exported via the package root:
+
+- `AUTH_TYPES` – Enum-like constants describing supported authentication flows (code, passkey, etc.)
+- `verifyAndExtractToken(token: string)` – Verifies a JWT (signature/structure) and returns a decoded payload or throws on failure.
+- `pkceChallengePair()` – Generates a secure PKCE code_verifier and corresponding code_challenge (S256).
+- `getToken(...)` / `getSession(...)` – Helpers to retrieve tokens / session data from storage or cookie contexts (implementation depends on consumer usage pattern).
+- `isGranted(roles: string[], required: string | string[])` – Authorization helper performing role / permission checks (deny-by-default pattern recommended).
+- `constants` – Centralized constants including JWT claim keys (`JWT.USER_ID_KEY`, etc.) and `API_TYPE` for discriminating API operations.
+
+> Keep a deny-by-default stance: always guard privileged operations with `isGranted` or equivalent server-side enforcement.
+
+## Usage Example
+
+```ts
+import {
+  AUTH_TYPES,
+  pkceChallengePair,
+  verifyAndExtractToken,
+  isGranted
+} from "@versini/auth-common";
+
+async function beginAuth() {
+  const { code_verifier, code_challenge } = await pkceChallengePair();
+  // send code_challenge to authorization endpoint, persist code_verifier securely (in-memory)
+}
+
+async function validate(idToken: string) {
+  const jwt = await verifyAndExtractToken(idToken);
+  if (!isGranted(jwt.payload.roles || [], "admin")) {
+    throw new Error("Not authorized");
+  }
+  return jwt.payload[AUTH_TYPES.AUTH];
+}
+```
+
+## Security Notes
+
+- Never persist the PKCE `code_verifier` beyond the user session in plaintext storage.
+- Avoid logging raw tokens; if needed log only the first/last 6 chars.
+- Perform server-side validation even if `verifyAndExtractToken` passes client-side.
+
+## TypeScript
+
+Distributed with full TypeScript declarations (`dist/*.d.ts`). All functions are strictly typed—avoid using `any`; prefer narrowing unknown data before passing to these helpers.
+
+## License
+
+MIT © gizmette.com

package/dist/index.d.ts

@@ -27,6 +27,7 @@ declare const JWT: {
     EXPIRES_AT_KEY: string;
     CREATED_AT_KEY: string;
     SCOPES_KEY: string;
+    SCOPE_KEY: string;
     CLIENT_ID_KEY: string;
     ISSUER: string;
 };
@@ -106,10 +107,11 @@ type ScopesGrants = {
  * Checks if the given encoded access token grants the required scopes.
  *
  * This function verifies the provided token and extracts its payload.
- * It then checks if the token contains the required scopes. The scopes can be provided
- * either as an array of strings or as a map of string arrays. When the scopes are provided
- * as a map, the function checks if the token contains at least one of the scopes in each
- * of the map's values (OR operation).
+ * It then checks if the token contains the required scopes. The function supports
+ * scopes in two formats: as an array of strings (JWT.SCOPES_KEY) or as a space-separated
+ * string (JWT.SCOPE_KEY). The scopes can be provided either as an array of strings or
+ * as a map of string arrays. When the scopes are provided as a map, the function checks
+ * if the token contains at least one of the scopes in each of the map's values (OR operation).
  *
  *
  * @async
@@ -141,10 +143,11 @@ declare const isGranted: (token: string, scopes: ScopesGrants) => Promise<boolea
  * Checks if the given non-encoded id token grants the required scopes.
  *
  * This function does not verify the token, it simply extracts its payload.
- * It then checks if the token contains the required scopes. The scopes can be provided
- * either as an array of strings or as a map of string arrays. When the scopes are provided
- * as a map, the function checks if the token contains at least one of the scopes in each
- * of the map's values (OR operation).
+ * It then checks if the token contains the required scopes. The function supports
+ * scopes in two formats: as an array of strings (JWT.SCOPES_KEY) or as a space-separated
+ * string (JWT.SCOPE_KEY). The scopes can be provided either as an array of strings or
+ * as a map of string arrays. When the scopes are provided as a map, the function checks
+ * if the token contains at least one of the scopes in each of the map's values (OR operation).
  *
  *
  * @function isGrantedSync