@flink-app/bankid-plugin 0.12.1-alpha.25 → 0.12.1-alpha.35

package/README.md

@@ -0,0 +1,777 @@
+# BankID Plugin
+
+A Flink plugin for Swedish BankID authentication and document signing. This plugin provides seamless integration with the Swedish BankID service for secure authentication and electronic signatures.
+
+## Features
+
+- BankID authentication (Mobile BankID and QR code)
+- Document signing with BankID
+- Automatic QR code generation and refresh
+- Session management with MongoDB
+- Test and production environments
+- Built-in HTTP endpoints (optional)
+- TypeScript support with full type safety
+
+## Installation
+
+```bash
+npm install @flink-app/bankid-plugin
+```
+
+## Prerequisites
+
+### 1. BankID Certificate
+
+You need a BankID certificate (PFX file) from your bank or the Swedish BankID organization:
+
+- **Test Environment**: Use test certificates from [BankID Test Environment](https://www.bankid.com/utvecklare/test)
+- **Production Environment**: Request a production certificate from your bank
+
+### 2. MongoDB Connection
+
+The plugin requires MongoDB to store BankID sessions.
+
+## Setup
+
+### Step 1: Prepare Certificate
+
+Convert your PFX certificate to base64:
+
+```bash
+# Convert PFX to base64
+cat certificate.pfx | base64 > certificate.txt
+```
+
+Store the base64 string in your environment variables:
+
+```bash
+BANKID_CERT_BASE64="MIIKZgIBAzCCCiw..."
+BANKID_PASSPHRASE="your-certificate-passphrase"
+```
+
+### Step 2: Configure Plugin
+
+**`index.ts`:**
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import { bankIdPlugin } from "@flink-app/bankid-plugin";
+import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+import { genericAuthPlugin, User } from "@flink-app/generic-auth-plugin";
+import { Ctx } from "./Ctx";
+
+function start() {
+  const app = new FlinkApp<Ctx>({
+    name: "My App",
+    auth: jwtAuthPlugin({
+      secret: process.env.JWT_SECRET!,
+      getUser: async (tokenData) => {
+        const user = await app.ctx.repos.userRepo.findById(tokenData.userId);
+        if (!user) throw new Error("User not found");
+        return {
+          id: user._id,
+          username: user.username,
+          roles: user.roles,
+        };
+      },
+      rolePermissions: {
+        user: ["read", "write"],
+      },
+    }),
+    db: {
+      uri: process.env.MONGODB_URI!,
+    },
+    plugins: [
+      genericAuthPlugin({
+        repoName: "userRepo",
+      }),
+      bankIdPlugin({
+        pfxBase64: process.env.BANKID_CERT_BASE64!,
+        passphrase: process.env.BANKID_PASSPHRASE!,
+        production: false, // Set to true for production
+        onGetEndUserIp: async (req) => {
+          // Get IP from X-Forwarded-For header if behind proxy
+          const forwardedFor = req.headers["x-forwarded-for"];
+          if (forwardedFor) {
+            return Array.isArray(forwardedFor)
+              ? forwardedFor[0]
+              : forwardedFor.split(",")[0];
+          }
+          return req.ip || "127.0.0.1";
+        },
+        onAuthSuccess: async (userData, ip, payload) => {
+          // Find or create user based on personal number
+          let user = await app.ctx.repos.userRepo.findOne({
+            personalNumber: userData.user.personalNumber,
+          });
+
+          if (!user) {
+            // Create new user
+            const createResult = await app.ctx.plugins.genericAuthPlugin.createUser(
+              app.ctx.repos.userRepo,
+              app.ctx.auth,
+              userData.user.personalNumber,
+              "", // No password for BankID users
+              "bankid",
+              ["user"],
+              {
+                name: userData.user.name,
+                givenName: userData.user.givenName,
+                surname: userData.user.surname,
+              },
+              undefined,
+              undefined,
+              userData.user.personalNumber
+            );
+
+            if (createResult.status !== "success") {
+              throw new Error("Failed to create user");
+            }
+
+            user = await app.ctx.repos.userRepo.findById(createResult.user!._id);
+          }
+
+          // Create JWT token
+          const token = await app.ctx.auth.createToken(
+            { userId: user!._id, username: user!.username },
+            user!.roles
+          );
+
+          return {
+            user: {
+              _id: user!._id,
+              username: user!.username,
+              profile: user!.profile,
+              roles: user!.roles,
+            },
+            token,
+          };
+        },
+        onSignSuccess: async (userData, signature, payload) => {
+          // Handle signed document
+          console.log("Document signed by:", userData.user.name);
+          console.log("Signature:", signature.signature);
+
+          // Store signature in database or process document
+          // Implementation depends on your use case
+        },
+      }),
+    ],
+  });
+
+  app.start();
+}
+
+start();
+```
+
+## Configuration Options
+
+### `BankIdPluginOptions`
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `pfxBase64` | `string` | Yes | - | BankID certificate in base64 format |
+| `passphrase` | `string` | Yes | - | Certificate passphrase |
+| `production` | `boolean` | No | `false` | Use production BankID environment |
+| `allowNoIp` | `boolean` | No | `false` | Allow requests without IP (uses 127.0.0.1) |
+| `onGetEndUserIp` | `Function` | Yes | - | Function to extract client IP address |
+| `onAuthSuccess` | `Function` | Yes | - | Callback when authentication succeeds |
+| `onSignSuccess` | `Function` | No | - | Callback when document signing succeeds |
+| `keepSessionsSec` | `number` | No | `86400` (24h) | How long to keep sessions in database |
+| `bankIdSessionsCollectionName` | `string` | No | `"bankid_sessions"` | MongoDB collection name for sessions |
+| `registerRoutes` | `boolean` | No | `true` | Register built-in HTTP endpoints |
+
+### Callback Functions
+
+#### `onGetEndUserIp(req: FlinkRequest): Promise<string>`
+
+Extract the end user's IP address from the request. Required by BankID for security.
+
+```typescript
+onGetEndUserIp: async (req) => {
+  // Behind a proxy
+  const forwardedFor = req.headers["x-forwarded-for"];
+  if (forwardedFor) {
+    return Array.isArray(forwardedFor)
+      ? forwardedFor[0]
+      : forwardedFor.split(",")[0];
+  }
+
+  // Direct connection
+  return req.ip || "127.0.0.1";
+}
+```
+
+#### `onAuthSuccess(userData, ip?, payload?): Promise<AuthSuccessCallbackResponse>`
+
+Called when BankID authentication is successful. Must return user object and JWT token.
+
+```typescript
+interface AuthSuccessCallbackResponse {
+  user: any;
+  token: string;
+}
+```
+
+**Parameters:**
+- `userData`: BankID user data including personal number and name
+- `ip`: Client IP address (optional)
+- `payload`: Custom payload passed during auth initiation (optional)
+
+#### `onSignSuccess(userData, signature, payload?): Promise<void>`
+
+Called when document signing is successful.
+
+**Parameters:**
+- `userData`: BankID user data
+- `signature`: Signature data including signature string and OCSP response
+- `payload`: Custom payload passed during sign initiation (optional)
+
+## Context API
+
+The plugin exposes the following functions via `ctx.plugins.bankId`:
+
+### `auth(options?): Promise<AuthResponse>`
+
+Initiate BankID authentication.
+
+```typescript
+const result = await ctx.plugins.bankId.auth({
+  endUserIp: "192.168.1.1",
+  payload: { returnUrl: "/dashboard" }, // Optional custom data
+});
+```
+
+**Returns:**
+```typescript
+interface AuthResponse {
+  orderRef: string;        // BankID order reference
+  autoStartToken: string;  // Token for Mobile BankID app
+  qr: string;             // QR code data URL for QR code authentication
+}
+```
+
+### `sign(options): Promise<SignResponse>`
+
+Initiate document signing.
+
+```typescript
+const result = await ctx.plugins.bankId.sign({
+  endUserIp: "192.168.1.1",
+  userVisibleData: "I approve this document",
+  userNonVisibleData: "Document ID: 12345", // Optional
+  payload: { documentId: "12345" },
+});
+```
+
+**Returns:**
+```typescript
+interface SignResponse {
+  orderRef: string;
+  autoStartToken: string;
+  qr: string;
+}
+```
+
+### `getAuthStatus(options): Promise<AuthStatusResponse>`
+
+Check authentication status and get result when complete.
+
+```typescript
+const result = await ctx.plugins.bankId.getAuthStatus({
+  orderRef: "abc123...",
+});
+```
+
+**Returns:**
+```typescript
+interface AuthStatusResponse {
+  status: "pending" | "complete" | "failed";
+  hintCode?: string;
+  qr?: string;          // Updated QR code if still pending
+  user?: any;           // User data when complete
+  token?: string;       // JWT token when complete
+}
+```
+
+### `getSignStatus(options): Promise<SignStatusResponse>`
+
+Check signing status and get result when complete.
+
+```typescript
+const result = await ctx.plugins.bankId.getSignStatus({
+  orderRef: "abc123...",
+});
+```
+
+### `cancelSession(options): Promise<CancelSessionResponse>`
+
+Cancel an ongoing BankID session.
+
+```typescript
+const result = await ctx.plugins.bankId.cancelSession({
+  orderRef: "abc123...",
+});
+```
+
+## Built-in API Endpoints
+
+When `registerRoutes: true` (default), the following endpoints are automatically available:
+
+### POST /bankid/auth
+
+Initiate BankID authentication.
+
+**Request:**
+```json
+{
+  "payload": {
+    "returnUrl": "/dashboard"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "data": {
+    "orderRef": "131daac9-16c6-4618-beb0-365768f37288",
+    "autoStartToken": "7c40b5c9-fa74-49cf-b98c-bfaf...",
+    "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
+  }
+}
+```
+
+### GET /bankid/auth?orderRef=xxx
+
+Get authentication status.
+
+**Query Parameters:**
+- `orderRef`: The order reference from initiation
+
+**Response (Pending):**
+```json
+{
+  "data": {
+    "status": "pending",
+    "hintCode": "outstandingTransaction",
+    "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
+  }
+}
+```
+
+**Response (Complete):**
+```json
+{
+  "data": {
+    "status": "complete",
+    "user": {
+      "_id": "507f1f77bcf86cd799439011",
+      "username": "198001011234",
+      "profile": {
+        "name": "John Doe",
+        "givenName": "John",
+        "surname": "Doe"
+      },
+      "roles": ["user"]
+    },
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
+```
+
+**Response (Failed):**
+```json
+{
+  "data": {
+    "status": "failed",
+    "hintCode": "userCancel"
+  }
+}
+```
+
+### GET /bankid/sign?orderRef=xxx
+
+Get signing status. Similar response structure to auth status.
+
+### DELETE /bankid/session/:orderRef
+
+Cancel a BankID session.
+
+**Response:**
+```json
+{
+  "data": {
+    "status": "success"
+  }
+}
+```
+
+## BankID Status Codes
+
+### Hint Codes (Pending)
+
+- `outstandingTransaction` - User hasn't opened BankID app yet
+- `noClient` - BankID app not installed
+- `started` - BankID app has been started
+- `userSign` - User is signing in BankID app
+
+### Hint Codes (Failed)
+
+- `userCancel` - User cancelled the operation
+- `expiredTransaction` - Session timed out
+- `certificateErr` - Certificate error
+- `startFailed` - Failed to start BankID app
+
+## Client Integration Examples
+
+### React Example with QR Code
+
+```typescript
+import React, { useState, useEffect } from "react";
+
+function BankIDLogin() {
+  const [orderRef, setOrderRef] = useState<string>();
+  const [qrCode, setQrCode] = useState<string>();
+  const [status, setStatus] = useState<string>("idle");
+
+  const initAuth = async () => {
+    const response = await fetch("/bankid/auth", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        payload: { returnUrl: "/dashboard" },
+      }),
+    });
+
+    const data = await response.json();
+    setOrderRef(data.data.orderRef);
+    setQrCode(data.data.qr);
+    setStatus("pending");
+  };
+
+  useEffect(() => {
+    if (!orderRef) return;
+
+    const interval = setInterval(async () => {
+      const response = await fetch(`/bankid/auth?orderRef=${orderRef}`);
+      const data = await response.json();
+
+      if (data.data.status === "complete") {
+        clearInterval(interval);
+        setStatus("complete");
+        // Store token and redirect
+        localStorage.setItem("token", data.data.token);
+        window.location.href = "/dashboard";
+      } else if (data.data.status === "failed") {
+        clearInterval(interval);
+        setStatus("failed");
+      } else {
+        // Update QR code if provided
+        if (data.data.qr) {
+          setQrCode(data.data.qr);
+        }
+      }
+    }, 2000); // Poll every 2 seconds
+
+    return () => clearInterval(interval);
+  }, [orderRef]);
+
+  return (
+    <div>
+      {status === "idle" && (
+        <button onClick={initAuth}>Login with BankID</button>
+      )}
+
+      {status === "pending" && (
+        <div>
+          <p>Scan QR code with BankID app:</p>
+          {qrCode && <img src={qrCode} alt="BankID QR Code" />}
+          <p>Or open BankID app on this device</p>
+        </div>
+      )}
+
+      {status === "failed" && (
+        <div>
+          <p>Authentication failed. Please try again.</p>
+          <button onClick={initAuth}>Retry</button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Mobile BankID Deep Link
+
+For mobile devices, use the `autoStartToken` to open the BankID app:
+
+```typescript
+const response = await fetch("/bankid/auth", { method: "POST" });
+const data = await response.json();
+
+// iOS and Android
+const bankIdUrl = `bankid:///?autostarttoken=${data.data.autoStartToken}&redirect=null`;
+window.location.href = bankIdUrl;
+
+// Then poll for status
+```
+
+## Document Signing
+
+### Sign a Document
+
+```typescript
+// In your handler
+const handler: Handler<Ctx, SignDocumentReq, SignDocumentRes> = async ({ ctx, req }) => {
+  const documentText = "I agree to the terms and conditions...";
+
+  const result = await ctx.plugins.bankId.sign({
+    endUserIp: await getClientIp(req),
+    userVisibleData: documentText,
+    userNonVisibleData: `Document ID: ${documentId}`,
+    payload: {
+      documentId,
+      userId: req.user.id,
+    },
+  });
+
+  return { data: result };
+};
+```
+
+### Handle Signed Document
+
+In your `onSignSuccess` callback:
+
+```typescript
+onSignSuccess: async (userData, signature, payload) => {
+  const { documentId, userId } = payload;
+
+  // Store signature
+  await ctx.repos.signatureRepo.create({
+    documentId,
+    userId,
+    personalNumber: userData.user.personalNumber,
+    name: userData.user.name,
+    signature: signature.signature,
+    ocspResponse: signature.ocspResponse,
+    signedAt: new Date(),
+  });
+
+  // Update document status
+  await ctx.repos.documentRepo.update(documentId, {
+    status: "signed",
+    signedBy: userData.user.personalNumber,
+  });
+}
+```
+
+## Session Management
+
+The plugin automatically manages BankID sessions in MongoDB:
+
+- Sessions are stored with automatic expiration (default: 24 hours)
+- QR codes are automatically regenerated every second while pending
+- Failed or completed sessions are cleaned up automatically
+
+### Custom Session Retention
+
+```typescript
+bankIdPlugin({
+  // ...other options
+  keepSessionsSec: 3600, // Keep sessions for 1 hour
+  bankIdSessionsCollectionName: "my_bankid_sessions",
+})
+```
+
+## Testing
+
+### Test Environment
+
+Use BankID test certificates and test personal numbers:
+
+```typescript
+bankIdPlugin({
+  production: false, // Test environment
+  pfxBase64: process.env.BANKID_TEST_CERT_BASE64!,
+  passphrase: process.env.BANKID_TEST_PASSPHRASE!,
+  // ...
+})
+```
+
+### Test Personal Numbers
+
+BankID provides test personal numbers for development:
+
+- `198001011234` - Standard test user
+- `198001021234` - Test user with multiple BankIDs
+
+See [BankID Test Documentation](https://www.bankid.com/utvecklare/test) for complete list.
+
+## Security Best Practices
+
+### 1. Certificate Security
+
+- Never commit certificates to version control
+- Store certificates in secure environment variables or secrets management
+- Use different certificates for test and production
+
+```bash
+# .env
+BANKID_CERT_BASE64=xxx
+BANKID_PASSPHRASE=yyy
+```
+
+### 2. IP Address Validation
+
+Always verify and log IP addresses:
+
+```typescript
+onGetEndUserIp: async (req) => {
+  const ip = extractIp(req);
+
+  // Log for audit
+  logger.info(`BankID request from IP: ${ip}`);
+
+  // Validate IP format
+  if (!isValidIp(ip)) {
+    throw new Error("Invalid IP address");
+  }
+
+  return ip;
+}
+```
+
+### 3. Rate Limiting
+
+Implement rate limiting on BankID endpoints to prevent abuse:
+
+```typescript
+import rateLimit from "express-rate-limit";
+
+app.use("/bankid", rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 10, // 10 requests per window
+}));
+```
+
+### 4. Session Validation
+
+Validate session state before completing authentication:
+
+```typescript
+onAuthSuccess: async (userData, ip, payload) => {
+  // Verify personal number format
+  if (!/^\d{12}$/.test(userData.user.personalNumber)) {
+    throw new Error("Invalid personal number");
+  }
+
+  // Additional validation...
+
+  return { user, token };
+}
+```
+
+### 5. HTTPS Only
+
+BankID requires HTTPS in production. Never use HTTP for BankID in production.
+
+## TypeScript Types
+
+```typescript
+import {
+  BankIdPluginOptions,
+  BankIdUserInfo,
+  BankIdSignature,
+  AuthSuccessCallbackResponse,
+  AuthResponse,
+  SignResponse,
+  AuthStatusResponse,
+  SignStatusResponse,
+  BankIdSession,
+} from "@flink-app/bankid-plugin";
+
+// User info from BankID
+interface BankIdUserInfo {
+  personalNumber: string;
+  name: string;
+  givenName: string;
+  surname: string;
+}
+
+// Signature data
+interface BankIdSignature {
+  signature: string;
+  ocspResponse: string;
+}
+
+// Auth success response
+interface AuthSuccessCallbackResponse {
+  user: any;
+  token: string;
+}
+```
+
+## Troubleshooting
+
+### QR Code Not Updating
+
+**Issue:** QR code becomes stale after 1 second
+
+**Solution:** The plugin automatically generates new QR codes. Ensure you're polling the status endpoint regularly (every 1-2 seconds).
+
+### Certificate Error
+
+**Issue:** `Error: unable to get local issuer certificate`
+
+**Solution:**
+- Verify certificate format is correct
+- Check passphrase is correct
+- Ensure certificate is valid for the environment (test/prod)
+
+### IP Address Issues
+
+**Issue:** `Failed to obtain endUserIp`
+
+**Solution:**
+```typescript
+// For development only
+bankIdPlugin({
+  allowNoIp: true, // Only for local development
+  onGetEndUserIp: async (req) => {
+    return req.ip || "127.0.0.1";
+  },
+})
+```
+
+### User Cancel
+
+**Issue:** Users frequently cancel
+
+**Solution:** Improve UX:
+- Show clear instructions
+- Display QR code prominently
+- Provide mobile deep link option
+- Show timeout countdown
+
+## Production Checklist
+
+- [ ] Use production BankID certificate
+- [ ] Set `production: true`
+- [ ] Configure HTTPS
+- [ ] Implement rate limiting
+- [ ] Set up monitoring and logging
+- [ ] Configure proper IP extraction behind proxy
+- [ ] Set appropriate session retention
+- [ ] Test certificate expiration handling
+- [ ] Configure error alerting
+- [ ] Validate personal number format
+
+## Complete Example
+
+See the configuration example at the beginning of this document for a complete working example integrating BankID with the Generic Auth Plugin.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flink-app/bankid-plugin",
-    "version": "0.12.1-alpha.25",
+    "version": "0.12.1-alpha.35",
     "description": "Flink plugin for Swedish BankID authentication and document signing",
     "scripts": {
         "test": "node --preserve-symlinks -r ts-node/register -- node_modules/jasmine/bin/jasmine --config=./spec/support/jasmine.json",
@@ -22,7 +22,7 @@
         "@types/node": "22.13.10"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.23",
+        "@flink-app/flink": "^0.12.1-alpha.35",
         "@types/jasmine": "^3.7.1",
         "@types/node": "22.13.10",
         "jasmine": "^3.7.0",
@@ -32,5 +32,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "44a1bf5bb2b2c7d18e4cecc06da626700639f82a"
+    "gitHead": "f8e8c6565a9ca1dd3e5fdb4c2a791c99ae3ba51a"
 }