XOCerberusAuth

XOCerberusAuth 是一個為 Fastify 框架量身打造的輕量級驗證套件庫，旨在簡化 Google OAuth 登入流程與 JWT (JSON Web Token) 的簽署與驗證工作。

🚀 特色

• Google OAuth 整合：輕鬆實作 Google 第三方登入。
• JWT 插件：內建非同步的 JWT 簽署與驗證機制。
• 高度型別安全：使用 TypeScript 撰寫，提供完善的型別定義與開發者體驗。
• Fastify 生態系：深度整合 Fastify 插件架構。

📦 安裝

使用 pnpm 安裝：

pnpm add xocerberus-auth

🛠 快速開始

1. 註冊 Google Auth 插件

import fastify from 'fastify';
import { googleAuthPlugin } from 'xocerberus-auth';

const app = fastify();

app.register(googleAuthPlugin, {
    clientId: 'YOUR_GOOGLE_CLIENT_ID',
    clientSecret: 'YOUR_GOOGLE_CLIENT_SECRET',
    redirectUri: 'http://localhost:3000/login/google/callback',
});

2. 註冊 JWT 插件

import { jwtPlugin } from 'xocerberus-auth';

app.register(jwtPlugin, {
    secret: 'your-very-secure-secret',
});

// 自定義 JWT Payload 型別 (選擇性)
declare module '@fastify/jwt' {
    interface FastifyJWT {
        payload: { userId: string; email: string };
        user: { userId: string; email: string };
    }
}

3. 使用驗證功能

// 簽署 JWT
app.get('/login', async (request, reply) => {
    const token = app.signJwt({ userId: '123', email: '[email protected]' });
    return { token };
});

// 驗證 JWT (使用內建的 checkJwt hook)
app.get('/profile', {
    preHandler: async (request, reply) => {
        try {
            await app.checkJwt(request);
        } catch (err) {
            reply.status(401).send({ error: '未授權' });
        }
    }
}, async (request) => {
    return request.user; // 驗證成功後可直接從 request.user 取得資料
});

📖 API 說明

googleAuthPlugin 選項

• clientId: Google Cloud Console 提供的 Client ID。
• clientSecret: Google Cloud Console 提供的 Client Secret。
• redirectUri: 使用者登入後的回後網址。

jwtPlugin 選項

• secret: 用於加密 JWT 的密鑰。

裝飾器 (Decorators)

插件會在 fastify 實例上註冊以下功能：

• fastify.signJwt(payload, expiresIn?): 簽署並回傳 JWT 字串。
• fastify.checkJwt(request): 驗證請求中的 JWT（通常放在 Authorization: Bearer <token>）。
• fastify.getGoogleAuthUserProfile(code): 透過 Google Auth Code 換取使用者資訊。

📄 授權

MIT License