@zapkey/express 1.0.0

package/README.md

@@ -0,0 +1,85 @@
+# @zapkey/express
+
+Express adapter for ZapKey.
+
+## Install
+
+```bash
+npm install @zapkey/core @zapkey/express express cookie-parser
+```
+
+## What it exports
+
+- `requireAuth`
+- `requireGuard`
+- `setAuthCookie`
+- `clearAuthCookie`
+- `handleLogin`
+- `handleRefresh`
+- `handleLogout`
+- `getUser`
+
+## Usage
+
+```ts
+import cookieParser from 'cookie-parser';
+import express from 'express';
+import { initZapkey } from '@zapkey/core';
+import { getUser, handleLogin, handleLogout, handleRefresh, requireAuth, requireGuard } from '@zapkey/express';
+import { MemoryAuthorizationStore, MemoryTokenStore } from '@zapkey/stores-memory';
+
+const authorization = new MemoryAuthorizationStore();
+authorization.addRole('user_123', 'admin');
+authorization.addRolePermission('admin', 'users:read');
+
+const sdk = initZapkey({
+  mode: 'session',
+  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
+  stores: {
+    token: new MemoryTokenStore(),
+    authorization,
+  },
+});
+
+const app = express();
+app.use(express.json());
+app.use(cookieParser());
+
+app.post('/auth/login', async (req, res) => {
+  const user = await authenticateUser(req.body.email, req.body.password);
+  if (!user) {
+    return res.status(401).json({ error: 'Invalid credentials' });
+  }
+
+  await handleLogin(sdk, user.id, res, {
+    metadata: { role: user.role },
+  });
+});
+
+app.post('/auth/refresh', (req, res) => handleRefresh(sdk, req, res));
+app.post('/auth/logout', (req, res) => handleLogout(sdk, req, res));
+
+app.get('/me', requireAuth(sdk), (req, res) => {
+  res.json({ userId: getUser(req).userId });
+});
+
+app.get(
+  '/admin/users',
+  requireAuth(sdk),
+  requireGuard(sdk, { type: 'permission', permission: 'users:read' }),
+  (_req, res) => {
+    res.json({ ok: true });
+  },
+);
+```
+
+## Notes
+
+- Register `cookie-parser` before using the auth helpers.
+- `requireAuth` checks the access-token cookie first and then falls back to the `Authorization` header.
+- `handleLogout` clears the access cookie and revokes the refresh token with reason `'logout'` when refresh mode is enabled.
+- Abuse protection is not automatic. Call `sdk.abuse.check(...)` from your routes when needed.
+
+## Full documentation
+
+See [`../../docs/SDK_USAGE_GUIDE.md`](../../docs/SDK_USAGE_GUIDE.md) for full configuration, enterprise profile, OTP, abuse, and store guidance.

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var f=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var g=Object.prototype.hasOwnProperty;var d=(e,t)=>{for(var o in t)f(e,o,{get:t[o],enumerable:!0})},O=(e,t,o,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of m(t))!g.call(e,n)&&n!==o&&f(e,n,{get:()=>t[n],enumerable:!(s=T(t,n))||s.enumerable});return e};var x=e=>O(f({},"__esModule",{value:!0}),e);var I={};d(I,{clearAuthCookie:()=>h,getUser:()=>N,handleLogin:()=>C,handleLogout:()=>E,handleRefresh:()=>A,requireAuth:()=>y,requireGuard:()=>l,setAuthCookie:()=>u});module.exports=x(I);var a=require("@zapkey/core");function y(e){return async(t,o,s)=>{try{let n=e.cookie.getAccessTokenName(),i=t.cookies?.[n];if(!i){let c=t.headers.authorization;c?.startsWith("Bearer ")&&(i=c.substring(7))}if(!i){o.status(401).json({error:"Unauthorized",code:"NO_TOKEN"});return}let r=await e.token.verifyAccessToken(i);t.user=r,s()}catch(n){k(n,o)}}}function l(e,t){return async(o,s,n)=>{try{if(!e.authorization){s.status(500).json({error:"Authorization not configured",code:"AUTHORIZATION_NOT_CONFIGURED",hint:"Provide AuthorizationStore in SDK config to use requireGuard"});return}let i=o.user;if(!i){s.status(401).json({error:"Unauthorized",code:"NO_USER"});return}await e.authorization.guard.enforce(i.userId,t),n()}catch(i){k(i,s)}}}function u(e,t,o,s){let n={httpOnly:s.httpOnly,secure:s.secure,sameSite:s.sameSite,maxAge:s.maxAge*1e3,path:s.path,domain:s.domain};e.cookie(t,o,n)}function h(e,t,o){let s={httpOnly:o.httpOnly,secure:o.secure,sameSite:o.sameSite,maxAge:0,path:o.path,domain:o.domain};e.clearCookie(t,s)}async function C(e,t,o,s){let n=s?.withRefresh??e.hasRefreshTokens(),i=s?.metadata!==void 0?{userId:t,metadata:s.metadata}:{userId:t};if(n){let r=await e.token.issue(i),c=e.cookie.getAccessTokenCookieOptions(r.expiresIn),p=e.getConfig().token.refreshTokenExpiresIn,R=e.cookie.getRefreshTokenCookieOptions(p);u(o,e.cookie.getAccessTokenName(),r.accessToken,c),u(o,e.cookie.getRefreshTokenName(),r.refreshToken,R),o.json({success:!0,accessToken:r.accessToken,expiresIn:r.expiresIn,refreshEnabled:!0})}else{let r=await e.token.issueAccessToken(i),c=e.cookie.getAccessTokenCookieOptions(r.expiresIn);u(o,e.cookie.getAccessTokenName(),r.accessToken,c),o.json({success:!0,accessToken:r.accessToken,expiresIn:r.expiresIn,refreshEnabled:!1})}}async function A(e,t,o){try{if(!e.hasRefreshTokens()||!e.token.rotate){o.status(400).json({error:"Refresh tokens are not enabled",code:"REFRESH_DISABLED",hint:"Set refreshTokens: true in SDK config to enable token refresh"});return}let s=t.cookies?.[e.cookie.getRefreshTokenName()];if(!s){o.status(401).json({error:"No refresh token",code:"NO_REFRESH_TOKEN"});return}let n=await e.token.rotate(s),i=e.cookie.getAccessTokenCookieOptions(n.expiresIn),r=e.getConfig().token.refreshTokenExpiresIn,c=e.cookie.getRefreshTokenCookieOptions(r);u(o,e.cookie.getAccessTokenName(),n.accessToken,i),u(o,e.cookie.getRefreshTokenName(),n.refreshToken,c),o.json({success:!0,accessToken:n.accessToken,expiresIn:n.expiresIn})}catch(s){k(s,o)}}async function E(e,t,o){try{let s=e.cookie.getClearCookieOptions();if(h(o,e.cookie.getAccessTokenName(),s),e.hasRefreshTokens()&&e.token.revokeToken){let n=t.cookies?.[e.cookie.getRefreshTokenName()];n&&await e.token.revokeToken(n,"logout"),h(o,e.cookie.getRefreshTokenName(),s)}o.json({success:!0})}catch(s){k(s,o)}}function k(e,t){e instanceof a.RateLimitError?t.status(e.statusCode).json({error:e.message,code:e.code,retryAfter:e.retryAfter}):e instanceof a.TokenError?t.status(e.statusCode).json({error:e.message,code:e.code}):e instanceof a.OTPError?t.status(e.statusCode).json({error:e.message,code:e.code}):e instanceof a.AuthorizationError?t.status(e.statusCode).json({error:e.message,code:e.code}):e instanceof a.AuthError?t.status(e.statusCode).json({error:e.message,code:e.code}):t.status(500).json({error:"Internal server error",code:"INTERNAL_ERROR"})}function N(e){return e.user}0&&(module.exports={clearAuthCookie,getUser,handleLogin,handleLogout,handleRefresh,requireAuth,requireGuard,setAuthCookie});

package/dist/index.d.cts

@@ -0,0 +1,76 @@
+import { Response, Request, RequestHandler } from 'express';
+import { CookieOptions, Zapkey, Guard } from '@zapkey/core';
+
+/**
+ * Express Adapter
+ *
+ * CRITICAL: This is a THIN adapter. NO business logic.
+ * Only request/response mapping.
+ *
+ * Supports both token modes:
+ * - Access-Only: Only access token in cookies, no refresh endpoint
+ * - Access + Refresh: Full token lifecycle with rotation
+ */
+
+/**
+ * Middleware to verify access token from cookie or Authorization header
+ *
+ * Works in BOTH modes (access-only and access+refresh)
+ */
+declare function requireAuth(sdk: Zapkey): RequestHandler;
+/**
+ * Middleware to enforce authorization guards
+ */
+declare function requireGuard(sdk: Zapkey, guard: Guard): RequestHandler;
+/**
+ * Cookie helper - set cookie with SDK options
+ */
+declare function setAuthCookie(res: Response, name: string, value: string, options: CookieOptions): void;
+/**
+ * Cookie helper - clear auth cookie
+ */
+declare function clearAuthCookie(res: Response, name: string, options: CookieOptions): void;
+/**
+ * Login handler helper
+ *
+ * Supports both modes:
+ * - Access-Only: Issues only access token, sets only access cookie
+ * - Access + Refresh: Issues token pair, sets both cookies
+ *
+ * Mode is determined by sdk.hasRefreshTokens()
+ *
+ * @param sdk - The Zapkey instance
+ * @param userId - User ID to issue tokens for
+ * @param res - Express response object
+ * @param options - Optional configuration
+ */
+declare function handleLogin(sdk: Zapkey, userId: string, res: Response, options?: {
+    metadata?: Record<string, unknown>;
+    /**
+     * Override refresh token behavior
+     * Default: sdk.hasRefreshTokens()
+     * Set to false to force access-only mode even if refresh is enabled
+     */
+    withRefresh?: boolean;
+}): Promise<void>;
+/**
+ * Refresh token handler
+ *
+ * NOTE: Only works when refreshTokens is enabled.
+ * Returns 400 error if called when refresh tokens are disabled.
+ */
+declare function handleRefresh(sdk: Zapkey, req: Request, res: Response): Promise<void>;
+/**
+ * Logout handler
+ *
+ * Works in both modes:
+ * - Access-Only: Just clears access cookie
+ * - Access + Refresh: Revokes refresh token and clears both cookies
+ */
+declare function handleLogout(sdk: Zapkey, req: Request, res: Response): Promise<void>;
+/**
+ * Get user from request (helper)
+ */
+declare function getUser(req: Request): any;
+
+export { clearAuthCookie, getUser, handleLogin, handleLogout, handleRefresh, requireAuth, requireGuard, setAuthCookie };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import { Response, Request, RequestHandler } from 'express';
+import { CookieOptions, Zapkey, Guard } from '@zapkey/core';
+
+/**
+ * Express Adapter
+ *
+ * CRITICAL: This is a THIN adapter. NO business logic.
+ * Only request/response mapping.
+ *
+ * Supports both token modes:
+ * - Access-Only: Only access token in cookies, no refresh endpoint
+ * - Access + Refresh: Full token lifecycle with rotation
+ */
+
+/**
+ * Middleware to verify access token from cookie or Authorization header
+ *
+ * Works in BOTH modes (access-only and access+refresh)
+ */
+declare function requireAuth(sdk: Zapkey): RequestHandler;
+/**
+ * Middleware to enforce authorization guards
+ */
+declare function requireGuard(sdk: Zapkey, guard: Guard): RequestHandler;
+/**
+ * Cookie helper - set cookie with SDK options
+ */
+declare function setAuthCookie(res: Response, name: string, value: string, options: CookieOptions): void;
+/**
+ * Cookie helper - clear auth cookie
+ */
+declare function clearAuthCookie(res: Response, name: string, options: CookieOptions): void;
+/**
+ * Login handler helper
+ *
+ * Supports both modes:
+ * - Access-Only: Issues only access token, sets only access cookie
+ * - Access + Refresh: Issues token pair, sets both cookies
+ *
+ * Mode is determined by sdk.hasRefreshTokens()
+ *
+ * @param sdk - The Zapkey instance
+ * @param userId - User ID to issue tokens for
+ * @param res - Express response object
+ * @param options - Optional configuration
+ */
+declare function handleLogin(sdk: Zapkey, userId: string, res: Response, options?: {
+    metadata?: Record<string, unknown>;
+    /**
+     * Override refresh token behavior
+     * Default: sdk.hasRefreshTokens()
+     * Set to false to force access-only mode even if refresh is enabled
+     */
+    withRefresh?: boolean;
+}): Promise<void>;
+/**
+ * Refresh token handler
+ *
+ * NOTE: Only works when refreshTokens is enabled.
+ * Returns 400 error if called when refresh tokens are disabled.
+ */
+declare function handleRefresh(sdk: Zapkey, req: Request, res: Response): Promise<void>;
+/**
+ * Logout handler
+ *
+ * Works in both modes:
+ * - Access-Only: Just clears access cookie
+ * - Access + Refresh: Revokes refresh token and clears both cookies
+ */
+declare function handleLogout(sdk: Zapkey, req: Request, res: Response): Promise<void>;
+/**
+ * Get user from request (helper)
+ */
+declare function getUser(req: Request): any;
+
+export { clearAuthCookie, getUser, handleLogin, handleLogout, handleRefresh, requireAuth, requireGuard, setAuthCookie };

package/dist/index.js

@@ -0,0 +1 @@
+import{AuthError as p,TokenError as R,OTPError as T,AuthorizationError as m,RateLimitError as g}from"@zapkey/core";function O(e){return async(s,o,t)=>{try{let n=e.cookie.getAccessTokenName(),i=s.cookies?.[n];if(!i){let a=s.headers.authorization;a?.startsWith("Bearer ")&&(i=a.substring(7))}if(!i){o.status(401).json({error:"Unauthorized",code:"NO_TOKEN"});return}let r=await e.token.verifyAccessToken(i);s.user=r,t()}catch(n){u(n,o)}}}function x(e,s){return async(o,t,n)=>{try{if(!e.authorization){t.status(500).json({error:"Authorization not configured",code:"AUTHORIZATION_NOT_CONFIGURED",hint:"Provide AuthorizationStore in SDK config to use requireGuard"});return}let i=o.user;if(!i){t.status(401).json({error:"Unauthorized",code:"NO_USER"});return}await e.authorization.guard.enforce(i.userId,s),n()}catch(i){u(i,t)}}}function c(e,s,o,t){let n={httpOnly:t.httpOnly,secure:t.secure,sameSite:t.sameSite,maxAge:t.maxAge*1e3,path:t.path,domain:t.domain};e.cookie(s,o,n)}function k(e,s,o){let t={httpOnly:o.httpOnly,secure:o.secure,sameSite:o.sameSite,maxAge:0,path:o.path,domain:o.domain};e.clearCookie(s,t)}async function y(e,s,o,t){let n=t?.withRefresh??e.hasRefreshTokens(),i=t?.metadata!==void 0?{userId:s,metadata:t.metadata}:{userId:s};if(n){let r=await e.token.issue(i),a=e.cookie.getAccessTokenCookieOptions(r.expiresIn),f=e.getConfig().token.refreshTokenExpiresIn,h=e.cookie.getRefreshTokenCookieOptions(f);c(o,e.cookie.getAccessTokenName(),r.accessToken,a),c(o,e.cookie.getRefreshTokenName(),r.refreshToken,h),o.json({success:!0,accessToken:r.accessToken,expiresIn:r.expiresIn,refreshEnabled:!0})}else{let r=await e.token.issueAccessToken(i),a=e.cookie.getAccessTokenCookieOptions(r.expiresIn);c(o,e.cookie.getAccessTokenName(),r.accessToken,a),o.json({success:!0,accessToken:r.accessToken,expiresIn:r.expiresIn,refreshEnabled:!1})}}async function l(e,s,o){try{if(!e.hasRefreshTokens()||!e.token.rotate){o.status(400).json({error:"Refresh tokens are not enabled",code:"REFRESH_DISABLED",hint:"Set refreshTokens: true in SDK config to enable token refresh"});return}let t=s.cookies?.[e.cookie.getRefreshTokenName()];if(!t){o.status(401).json({error:"No refresh token",code:"NO_REFRESH_TOKEN"});return}let n=await e.token.rotate(t),i=e.cookie.getAccessTokenCookieOptions(n.expiresIn),r=e.getConfig().token.refreshTokenExpiresIn,a=e.cookie.getRefreshTokenCookieOptions(r);c(o,e.cookie.getAccessTokenName(),n.accessToken,i),c(o,e.cookie.getRefreshTokenName(),n.refreshToken,a),o.json({success:!0,accessToken:n.accessToken,expiresIn:n.expiresIn})}catch(t){u(t,o)}}async function C(e,s,o){try{let t=e.cookie.getClearCookieOptions();if(k(o,e.cookie.getAccessTokenName(),t),e.hasRefreshTokens()&&e.token.revokeToken){let n=s.cookies?.[e.cookie.getRefreshTokenName()];n&&await e.token.revokeToken(n,"logout"),k(o,e.cookie.getRefreshTokenName(),t)}o.json({success:!0})}catch(t){u(t,o)}}function u(e,s){e instanceof g?s.status(e.statusCode).json({error:e.message,code:e.code,retryAfter:e.retryAfter}):e instanceof R?s.status(e.statusCode).json({error:e.message,code:e.code}):e instanceof T?s.status(e.statusCode).json({error:e.message,code:e.code}):e instanceof m?s.status(e.statusCode).json({error:e.message,code:e.code}):e instanceof p?s.status(e.statusCode).json({error:e.message,code:e.code}):s.status(500).json({error:"Internal server error",code:"INTERNAL_ERROR"})}function A(e){return e.user}export{k as clearAuthCookie,A as getUser,y as handleLogin,C as handleLogout,l as handleRefresh,O as requireAuth,x as requireGuard,c as setAuthCookie};

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "@zapkey/express",
+    "version": "1.0.0",
+    "description": "Express adapter for ZapKey authentication SDK",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "test": "vitest run",
+        "lint": "eslint src --ext .ts",
+        "typecheck": "tsc --noEmit",
+        "clean": "rimraf dist"
+    },
+    "keywords": [
+        "zapkey",
+        "express",
+        "authentication",
+        "adapter"
+    ],
+    "author": "",
+    "license": "MIT",
+    "peerDependencies": {
+        "@zapkey/core": "^1.0.0",
+        "express": "^4.18.0 || ^5.0.0"
+    },
+    "devDependencies": {
+        "@zapkey/core": "^1.0.0",
+        "@types/express": "^5.0.6",
+        "@types/node": "^20.11.5",
+        "express": "^5.0.0",
+        "rimraf": "^5.0.5",
+        "tsup": "^8.0.1",
+        "typescript": "^5.3.3",
+        "vitest": "^1.2.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}