@versini/auth-common 4.5.0 → 4.6.0

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

@@ -8,6 +8,7 @@ declare const AUTH_TYPES: {
     REFRESH_TOKEN: string;
     PASSKEY: string;
     AUTH0: string;
+    GOOGLE: string;
 };
 declare const HEADERS: {
     CLIENT_ID: string;
@@ -42,6 +43,7 @@ declare const API_TYPE: {
     LOGOUT: string;
     LOGIN: string;
     REFRESH: string;
+    GOOGLE: string;
 };
 
 declare const verifyAndExtractToken: (token: string) => Promise<jose.JWTVerifyResult<jose.JWTPayload> | undefined>;