feat: comprehensive security and type safety improvements

Security fixes (P0):
- Use timing-safe comparison for webhook signature verification
- Remove signature bypass vulnerability (throw error instead of warn+continue)

Feature improvements (P1):
- Export multicast and richMenu from @linekit/messaging
- Add input validation for reply, push, multicast functions
- Add proper Message type definitions with all LINE message types

Type safety (P2):
- Replace `any` with proper types across all packages
- Add isReplyableEvent type guard for Context
- Add WebhookRequest/WebhookResponse interfaces for router
- Add LineAPIErrorResponse type for error handling
- Add RichMenuAction interface

Error handling (P2):
- Add LineLoginError class to @linekit/login
- Handle JSON.parse failures in client.ts
- Add onError callback option to router

OAuth helpers (P3):
- Add generateState() for CSRF protection
- Add validateState() with timing-safe comparison
- Add generateNonce() for ID token validation

Documentation:
- Update README with security features
- Add LINE Login OAuth flow example with state validation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kevintseng

README.md

@@ -12,6 +12,7 @@ A modular integration toolkit for LINE Messaging API, Login, and LIFF.
 - **Modular**: separate packages for Core, Messaging, Login, and Adapters.
 - **Framework Agnostic**: use with Express, Fastify, or standard Web APIs.
 - **Type-Safe**: written in TypeScript with complete definitions.
+- **Secure**: timing-safe signature verification, input validation, CSRF protection helpers.
 - **Developer Friendly**: simple, explicit API for bots and login.
 
 ## Installation
@@ -59,18 +60,29 @@ app.listen(3000, () => console.log("Bot running on port 3000"));
 ### LINE Login
 
 ```ts
-import { login } from "@linekit/login";
-
-// Verify ID Token from client
-const user = await login.verify(idToken, channelId);
-console.log(user.name, user.email);
+import { login, generateAuthUrl, issueAccessToken } from "@linekit/login";
+
+// Generate OAuth URL with CSRF protection
+const state = login.generateState();
+const authUrl = generateAuthUrl({
+  channelId: "YOUR_CHANNEL_ID",
+  redirectUri: "https://example.com/callback",
+  state,
+});
+
+// After callback, validate state and exchange code for tokens
+if (login.validateState(savedState, returnedState)) {
+  const tokens = await issueAccessToken(channelId, channelSecret, code, redirectUri);
+  const user = await login.verify(tokens.id_token, channelId);
+  console.log(user.name, user.email);
+}
 ```
 
 ## Packages
 
-- **@linekit/core**: Webhook verification, Context, Router.
-- **@linekit/messaging**: Messaging API client (Reply, Push, Multicast).
-- **@linekit/login**: OAuth and ID Token verification.
+- **@linekit/core**: Webhook verification (timing-safe), Context, Router with error handling.
+- **@linekit/messaging**: Messaging API client (Reply, Push, Multicast, Rich Menu) with input validation.
+- **@linekit/login**: OAuth flow, ID Token verification, CSRF state helpers.
 - **@linekit/express**: Adapter for Express.js.
 
 ## Documentation

README.zh-TW.md

@@ -12,6 +12,7 @@
 - **模組化**：將 Core、Messaging、Login 和 Adapters 分離為獨立套件。
 - **框架無關**：可與 Express、Fastify 或標準 Web API 一起使用。
 - **型別安全**：使用 TypeScript 編寫，提供完整的型別定義。
+- **安全性**：時序安全的簽章驗證、輸入驗證、CSRF 保護工具。
 - **開發者友善**：為機器人和登入功能提供簡單、明確的 API。
 
 ## 安裝
@@ -59,18 +60,29 @@ app.listen(3000, () => console.log("Bot running on port 3000"));
 ### LINE Login
 
 ```ts
-import { login } from "@linekit/login";
-
-// 驗證來自客戶端的 ID Token
-const user = await login.verify(idToken, channelId);
-console.log(user.name, user.email);
+import { login, generateAuthUrl, issueAccessToken } from "@linekit/login";
+
+// 產生含 CSRF 保護的 OAuth URL
+const state = login.generateState();
+const authUrl = generateAuthUrl({
+  channelId: "YOUR_CHANNEL_ID",
+  redirectUri: "https://example.com/callback",
+  state,
+});
+
+// 回調後驗證 state 並交換 token
+if (login.validateState(savedState, returnedState)) {
+  const tokens = await issueAccessToken(channelId, channelSecret, code, redirectUri);
+  const user = await login.verify(tokens.id_token, channelId);
+  console.log(user.name, user.email);
+}
 ```
 
 ## 套件列表
 
-- **@linekit/core**: Webhook 驗證、Context、Router。
-- **@linekit/messaging**: Messaging API 客戶端 (Reply, Push, Multicast)。
-- **@linekit/login**: OAuth 和 ID Token 驗證。
+- **@linekit/core**: Webhook 驗證（時序安全）、Context、Router 含錯誤處理。
+- **@linekit/messaging**: Messaging API 客戶端 (Reply, Push, Multicast, Rich Menu) 含輸入驗證。
+- **@linekit/login**: OAuth 流程、ID Token 驗證、CSRF state 工具。
 - **@linekit/express**: Express.js 的適配器。
 
 ## 文件

packages/core/src/context.ts

@@ -1,11 +1,9 @@
 import {
-    replyText,
     replyMessage,
-    pushText,
     pushMessage,
     Message,
 } from "@linekit/messaging";
-import { WebhookEvent, LineAppConfig } from "./types.js";
+import { WebhookEvent, LineAppConfig, isReplyableEvent } from "./types.js";
 
 export class Context {
     public readonly event: WebhookEvent;
@@ -21,7 +19,7 @@ export class Context {
     }
 
     get replyToken(): string | undefined {
-        return (this.event as any).replyToken;
+        return isReplyableEvent(this.event) ? this.event.replyToken : undefined;
     }
 
     public async reply(messages: Message[] | Message) {

packages/core/src/router.ts

@@ -2,13 +2,34 @@ import { Context } from "./context.js";
 import { LineAppConfig, WebhookEvent } from "./types.js";
 
 type EventHandler = (ctx: Context) => Promise<void> | void;
+type ErrorHandler = (error: Error, ctx: Context) => Promise<void> | void;
 
 export interface RouterHandlers {
     [key: string]: EventHandler;
 }
 
-export function createRouter(config: LineAppConfig, handlers: RouterHandlers) {
-    return async (req: any, res: any) => {
+export interface RouterOptions {
+    onError?: ErrorHandler;
+}
+
+// Minimal request/response interfaces for framework compatibility
+interface WebhookRequest {
+    body?: {
+        events?: WebhookEvent[];
+    };
+}
+
+interface WebhookResponse {
+    status?: (code: number) => WebhookResponse;
+    end?: () => void;
+}
+
+export function createRouter(
+    config: LineAppConfig,
+    handlers: RouterHandlers,
+    options: RouterOptions = {}
+) {
+    return async (req: WebhookRequest, res?: WebhookResponse) => {
         // Expect req.body.events to be present (handled by webhook middleware)
         const events: WebhookEvent[] = req.body?.events || [];
 
@@ -20,18 +41,24 @@ export function createRouter(config: LineAppConfig, handlers: RouterHandlers) {
                     try {
                         await handler(ctx);
                     } catch (err) {
-                        console.error(`Error handling event ${event.type}:`, err);
-                        // We generally absorb errors in handlers to avoid crashing the loop, 
-                        // but strictly speaking we might want to let it bubble if the user wants.
-                        // For a framework, logging and continuing is usually safer for webhooks.
+                        const error = err instanceof Error ? err : new Error(String(err));
+                        if (options.onError) {
+                            try {
+                                await options.onError(error, ctx);
+                            } catch (onErrorErr) {
+                                console.error(`Error in onError handler:`, onErrorErr);
+                            }
+                        } else {
+                            console.error(`Error handling event ${event.type}:`, error);
+                        }
                     }
                 }
             })
         );
 
         // If res is provided (Express-like), send 200
         if (res && typeof res.status === "function") {
-            res.status(200).end();
+            res.status(200).end?.();
         }
     };
 }

packages/core/src/types.ts

@@ -133,11 +133,20 @@ export interface PostbackEvent extends EventBase {
     replyToken: string;
     postback: {
         data: string;
-        params?: Record<string, any>;
+        params?: Record<string, string>;
     };
 }
 
 export interface UnknownEvent extends EventBase {
     type: string;
-    [key: string]: any;
+    replyToken?: string;
+    [key: string]: unknown;
+}
+
+// Helper type for events that can be replied to
+export type ReplyableEvent = MessageEvent | FollowEvent | PostbackEvent;
+
+// Type guard for replyable events
+export function isReplyableEvent(event: WebhookEvent): event is ReplyableEvent {
+    return "replyToken" in event && typeof (event as ReplyableEvent).replyToken === "string";
 }

packages/core/src/webhook.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "http";
-import * as crypto from "crypto";
+import { createHmac, timingSafeEqual } from "crypto";
 import { SignatureValidationFailedError, JSONParseError } from "./errors.js";
 
 interface WebhookConfig {
@@ -47,31 +47,25 @@ export function createWebhookMiddleware(config: WebhookConfig) {
             }
 
             if (!body) {
-                // Fallback strategy: strictly speaking we need the raw string bytes for signature.
-                // If the framework already parsed it to JSON and discarded raw bytes, we can't strictly verify signature 
-                // without reconstruction (which is flaky).
-                // For now, we assume rawBody string is available or we just read it.
-                // If body is missing, we can't verify.
-                if (req.body && typeof req.body === 'object') {
-                    // Dangerous fallback: stringify. Only works if keys are ordered same way.
-                    // Ideally we throw or warn.
-                    console.warn("linekit: rawBody not found, skipping signature verification is NOT RECOMMENDED. Please ensure raw body is available.");
-                    return next?.();
-                }
-                throw new Error("Missing request body for signature verification");
+                // rawBody is required for signature verification
+                // If the framework already parsed it to JSON and discarded raw bytes, we cannot verify
+                throw new SignatureValidationFailedError("Cannot verify signature: rawBody not available. Please configure your framework to preserve raw body.");
             }
 
             if (!signature) {
                 throw new SignatureValidationFailedError("Missing X-Line-Signature header");
             }
 
-            const hash = crypto
-                .createHmac("sha256", config.channelSecret)
+            const hash = createHmac("sha256", config.channelSecret)
                 .update(body)
                 .digest("base64");
 
-            if (hash !== signature) {
-                // use safe constant time comparison if possible, but string check is standard in many examples.
+            // Use timing-safe comparison to prevent timing attacks
+            const hashBuffer = Buffer.from(hash);
+            const signatureBuffer = Buffer.from(signature);
+
+            if (hashBuffer.length !== signatureBuffer.length ||
+                !timingSafeEqual(hashBuffer, signatureBuffer)) {
                 throw new SignatureValidationFailedError();
             }
 

packages/login/src/errors.ts

@@ -0,0 +1,11 @@
+export class LineLoginError extends Error {
+    public code?: string;
+    public status?: number;
+
+    constructor(message: string, code?: string, status?: number) {
+        super(message);
+        this.name = "LineLoginError";
+        this.code = code;
+        this.status = status;
+    }
+}

packages/login/src/index.ts

@@ -1,8 +1,15 @@
 export * from "./verify.js";
 export * from "./oauth.js";
+export * from "./errors.js";
+export * from "./state.js";
 
-// Facade for convenience (as requested by user)
+// Facade for convenience
 import { verifyIdToken } from "./verify.js";
+import { generateState, validateState, generateNonce } from "./state.js";
+
 export const login = {
-    verify: verifyIdToken
+    verify: verifyIdToken,
+    generateState,
+    validateState,
+    generateNonce,
 };

packages/login/src/oauth.ts

@@ -1,3 +1,5 @@
+import { LineLoginError } from "./errors.js";
+
 export interface GenerateAuthUrlOptions {
     channelId: string;
     redirectUri: string;
@@ -8,6 +10,16 @@ export interface GenerateAuthUrlOptions {
 }
 
 export function generateAuthUrl(options: GenerateAuthUrlOptions): string {
+    if (!options.channelId) {
+        throw new LineLoginError("channelId is required", "INVALID_PARAMETER");
+    }
+    if (!options.redirectUri) {
+        throw new LineLoginError("redirectUri is required", "INVALID_PARAMETER");
+    }
+    if (!options.state) {
+        throw new LineLoginError("state is required for CSRF protection", "INVALID_PARAMETER");
+    }
+
     const params = new URLSearchParams();
     params.append('response_type', 'code');
     params.append('client_id', options.channelId);
@@ -36,6 +48,19 @@ export async function issueAccessToken(
     code: string,
     redirectUri: string
 ): Promise<IssueAccessTokenResponse> {
+    if (!channelId) {
+        throw new LineLoginError("channelId is required", "INVALID_PARAMETER");
+    }
+    if (!channelSecret) {
+        throw new LineLoginError("channelSecret is required", "INVALID_PARAMETER");
+    }
+    if (!code) {
+        throw new LineLoginError("authorization code is required", "INVALID_PARAMETER");
+    }
+    if (!redirectUri) {
+        throw new LineLoginError("redirectUri is required", "INVALID_PARAMETER");
+    }
+
     const params = new URLSearchParams();
     params.append('grant_type', 'authorization_code');
     params.append('code', code);
@@ -52,8 +77,12 @@ export async function issueAccessToken(
     });
 
     if (!res.ok) {
-        const err = await res.text();
-        throw new Error(`Failed to issue access token: ${res.statusText} ${err}`);
+        const errorText = await res.text();
+        throw new LineLoginError(
+            `Failed to issue access token: ${res.statusText}`,
+            "TOKEN_ISSUE_FAILED",
+            res.status
+        );
     }
 
     return res.json();

packages/login/src/state.ts

@@ -0,0 +1,41 @@
+import { randomBytes } from "crypto";
+
+/**
+ * Generate a cryptographically secure random state string for OAuth CSRF protection.
+ * @param length - Length of the random bytes (default: 32, resulting in 64 hex characters)
+ * @returns A random hex string
+ */
+export function generateState(length: number = 32): string {
+    return randomBytes(length).toString("hex");
+}
+
+/**
+ * Validate that the returned state matches the expected state.
+ * Uses timing-safe comparison to prevent timing attacks.
+ * @param expected - The state that was sent in the authorization request
+ * @param actual - The state returned from the authorization server
+ * @returns true if states match, false otherwise
+ */
+export function validateState(expected: string, actual: string): boolean {
+    if (!expected || !actual) {
+        return false;
+    }
+    if (expected.length !== actual.length) {
+        return false;
+    }
+    // Simple timing-safe comparison for strings
+    let result = 0;
+    for (let i = 0; i < expected.length; i++) {
+        result |= expected.charCodeAt(i) ^ actual.charCodeAt(i);
+    }
+    return result === 0;
+}
+
+/**
+ * Generate a cryptographically secure nonce for ID token validation.
+ * @param length - Length of the random bytes (default: 32)
+ * @returns A random hex string
+ */
+export function generateNonce(length: number = 32): string {
+    return randomBytes(length).toString("hex");
+}