@bool-ts/guard-sdk 1.0.0-beta.1

package/dist/instances/client.d.ts

@@ -0,0 +1,47 @@
+import type { IClient, TClientConfigs, TClientOptions } from "../interfaces/client.interface";
+export declare class Client implements IClient {
+    #private;
+    private readonly configs;
+    private readonly options?;
+    private token;
+    /**
+     * Initialize BoolGuard client instance
+     * @param configs
+     * @param options
+     */
+    constructor(configs: TClientConfigs, options?: TClientOptions | undefined);
+    /**
+     * Sign JWT token with Ed25519 algorithm
+     * @returns
+     */
+    signToken(): Promise<string>;
+    /**
+     * Ping to BoolGuard service to check if the service is reachable
+     * This action should be done before any other actions.
+     * @returns
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Create a new plain account with custom account name
+     * @param args
+     * @returns
+     */
+    createPlainAccount({ identity, password, metadata }: Parameters<IClient["createPlainAccount"]>[number]): ReturnType<IClient["createPlainAccount"]>;
+    /**
+     * Create a new email account, this action will create email record and link to account
+     * with random account alias generated by system.
+     * @param args
+     */
+    createEmailAccount({ identity, password, metadata }: Parameters<IClient["createEmailAccount"]>[number]): ReturnType<IClient["createEmailAccount"]>;
+    /**
+     * Authenticate an account with account name and password
+     * This action will return account info and JWT token if successful
+     * @param param0
+     */
+    authenticate({ identity, password }: Parameters<IClient["authenticate"]>[number]): ReturnType<IClient["authenticate"]>;
+    /**
+     * Authenticate a token and return account info if token is valid
+     * @param param0
+     */
+    verifyToken({ token }: Parameters<IClient["verifyToken"]>[number]): ReturnType<IClient["verifyToken"]>;
+}

package/dist/instances/index.d.ts

@@ -0,0 +1 @@
+export { Client } from "./client";

package/dist/interfaces/account.interface.d.ts

@@ -0,0 +1,6 @@
+export type TDefaultAccountMetadata = Record<string, string | number | Date | null | undefined>;
+export interface IAccount<T = TDefaultAccountMetadata> {
+    uuid: string;
+    status: string;
+    metadata?: T | null;
+}

package/dist/interfaces/accountCredential.interface.d.ts

@@ -0,0 +1,7 @@
+export interface IAccountCredential {
+    uuid: string;
+    identity: string;
+    status: string;
+    type: string;
+    isVerified: boolean;
+}

package/dist/interfaces/base.d.ts

@@ -0,0 +1,3 @@
+export type TApiResponse<T> = Readonly<{
+    data: Awaited<ReturnType<T extends (...args: any) => Promise<infer R> ? () => R : never>>;
+}>;

package/dist/interfaces/client.interface.d.ts

@@ -0,0 +1,48 @@
+import type { IAccount, TDefaultAccountMetadata } from "./account.interface";
+import type { IAccountCredential } from "./accountCredential.interface";
+export type TClientConfigs = {
+    tenantId: string;
+    appId: string;
+    modeId: string;
+    secretKey: string;
+};
+export type TClientOptions = {
+    version?: 1;
+    logs?: boolean;
+};
+export interface IClient<TAccountMetadata extends TDefaultAccountMetadata = TDefaultAccountMetadata> {
+    createPlainAccount(args: {
+        identity: string;
+        password: string;
+        metadata?: TAccountMetadata | null;
+    }): Promise<Readonly<{
+        account: IAccount<TAccountMetadata>;
+        credential: IAccountCredential;
+    }>>;
+    createEmailAccount(args: {
+        identity: string;
+        password: string | null;
+        metadata?: TAccountMetadata | null;
+    }): Promise<Readonly<{
+        account: IAccount<TAccountMetadata>;
+        credential: IAccountCredential;
+    }>>;
+    authenticate(args: {
+        identity: string;
+        password?: string | null;
+    }): Promise<{
+        token: string;
+        account: IAccount<TAccountMetadata>;
+        credential: IAccountCredential;
+    }>;
+    verifyToken(args: {
+        token: string;
+    }): Promise<{
+        account: IAccount<TAccountMetadata>;
+        credential: IAccountCredential;
+    }>;
+}
+export type TAuthState = {
+    account: IAccount;
+    credential: IAccountCredential;
+};

package/dist/interfaces/index.d.ts

@@ -0,0 +1,4 @@
+export type { IAccount } from "./account.interface";
+export type { IAccountCredential } from "./accountCredential.interface";
+export type { TApiResponse } from "./base";
+export type { IClient, TAuthState, TClientConfigs, TClientOptions } from "./client.interface";

package/package.json

@@ -0,0 +1,50 @@
+{
+    "author": "Trần Đức Tâm (Neo)",
+    "bugs": {
+        "url": "https://github.com/BoolTS/guard-sdk/issues"
+    },
+    "dependencies": {
+        "jose": "^6.1.0",
+        "reflect-metadata": "^0.2.2",
+        "zod": "^4.1.9"
+    },
+    "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5.9.2"
+    },
+    "files": [
+        "./dist",
+        "./src"
+    ],
+    "homepage": "https://github.com/BoolTS/guard-sdk#readme",
+    "keywords": [
+        "bool",
+        "typescript",
+        "ts",
+        "bun",
+        "framework",
+        "guards",
+        "security",
+        "SDK"
+    ],
+    "license": "MIT",
+    "main": "./dist/index.js",
+    "name": "@bool-ts/guard-sdk",
+    "peerDependencies": {
+        "@bool-ts/core": "^2.0.3"
+    },
+    "private": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/BoolTS/guard-sdk.git"
+    },
+    "scripts": {
+        "build": "tsc --emitDeclarationOnly && bun run app.build.ts",
+        "test": "bun --hot run __test/index.ts"
+    },
+    "types": "./dist/index.d.ts",
+    "version": "1.0.0-beta.1"
+}

package/src/constants/enums.ts

@@ -0,0 +1,3 @@
+export enum ETokenAudiences {
+    SYSTEM = "https://api-guard.booljs.com"
+}

package/src/constants/index.ts

@@ -0,0 +1,2 @@
+export * as Enums from "./enums";
+export * as Keys from "./keys";

package/src/constants/keys.ts

@@ -0,0 +1,4 @@
+export const authState = Symbol("__boolGuard::authState");
+export const guardMetadata = Symbol("__boolGuard::guardMetadata");
+export const service = Symbol("__boolGuard::authService");
+export const guardClient = Symbol("__boolGuard::guardClient");

package/src/decorators/actionGuard.decorator.ts

@@ -0,0 +1,5 @@
+import { Keys } from "../constants";
+
+export const ActionGuard = () => (target: Object, methodName: string) => {
+    Reflect.defineMetadata(Keys.guardMetadata, undefined, target, methodName);
+};

package/src/decorators/authState.decorator.ts

@@ -0,0 +1,4 @@
+import { Context } from "@bool-ts/core";
+import { Keys } from "../constants";
+
+export const AuthState = () => Context(Keys.authState);

package/src/decorators/controllerGuard.decorator.ts

@@ -0,0 +1,5 @@
+import { Keys } from "../constants";
+
+export const ControllerGuard = () => (target: Object) => {
+    Reflect.defineMetadata(Keys.guardMetadata, undefined, target);
+};

package/src/decorators/index.ts

@@ -0,0 +1,3 @@
+export { ActionGuard } from "./actionGuard.decorator";
+export { AuthState } from "./authState.decorator";
+export { ControllerGuard } from "./controllerGuard.decorator";

package/src/entities/index.ts

@@ -0,0 +1,2 @@
+export * from "./interceptor";
+export * from "./middleware";

package/src/entities/interceptor.ts

@@ -0,0 +1,47 @@
+import type { IInterceptor, THttpRouteModel } from "@bool-ts/core";
+import type { TAuthState } from "../interfaces/client.interface";
+
+import { Interceptor as BoolInterceptor, HttpClientError, RouteModel } from "@bool-ts/core";
+import { Keys } from "../constants";
+import { AuthState } from "../decorators/authState.decorator";
+
+@BoolInterceptor()
+export class Interceptor implements IInterceptor {
+    open(
+        @RouteModel()
+        routeModel: THttpRouteModel,
+        @AuthState()
+        authState: TAuthState
+    ) {
+        const actionMetadataKeys = Reflect.getOwnMetadataKeys(
+            routeModel.class.prototype,
+            routeModel.funcName
+        );
+
+        if (actionMetadataKeys.includes(Keys.authState)) {
+            if (!authState) {
+                throw new HttpClientError({
+                    httpCode: 401,
+                    message: "Unauthorized",
+                    data: undefined
+                });
+            }
+
+            return;
+        }
+
+        const controllerMetadataKeys = Reflect.getOwnMetadataKeys(routeModel.class);
+
+        if (controllerMetadataKeys.includes(Keys.authState)) {
+            if (!authState) {
+                throw new HttpClientError({
+                    httpCode: 401,
+                    message: "Unauthorized",
+                    data: undefined
+                });
+            }
+
+            return;
+        }
+    }
+}

package/src/entities/loader.ts

@@ -0,0 +1,20 @@
+import type { TClientConfigs, TClientOptions } from "../interfaces/client.interface";
+
+import { Keys } from "../constants";
+import { Client } from "../instances/client";
+
+export const loader = async (clientConfigs: TClientConfigs, clientOptions?: TClientOptions) => {
+    const boolGuardClient = new Client(clientConfigs, clientOptions);
+
+    await boolGuardClient.signToken();
+
+    const pingResult = await boolGuardClient.ping();
+
+    if (!pingResult) {
+        throw new Error("Ping to Bool Guard service failed!");
+    }
+
+    return [Keys.guardClient, boolGuardClient];
+};
+
+export default loader;

package/src/entities/middleware.ts

@@ -0,0 +1,73 @@
+import type { IContext, IMiddleware } from "@bool-ts/core";
+import type { IClient, TAuthState } from "../interfaces/client.interface";
+
+import { Context, Inject, RequestHeaders } from "@bool-ts/core";
+import { object, string } from "zod/v4";
+import { Keys } from "../constants";
+import { Client } from "../instances";
+
+const headersSchema = object({
+    authorization: string()
+        .startsWith("Bearer ")
+        .min(24)
+        .transform((value) => {
+            const [schema, token] = value.split(" ");
+
+            return Object.freeze({
+                schema,
+                token
+            });
+        })
+});
+
+/**
+ * Bool guard middleware for Bool Typescript framework
+ */
+export class Middleware implements IMiddleware {
+    /**
+     *
+     * @param tenantAppModesService
+     */
+    constructor(
+        @Inject(Client)
+        private readonly clientInstance: IClient
+    ) {}
+
+    /**
+     *
+     * @param context
+     * @param requestHeaders
+     */
+    async start(
+        @Context()
+        context: IContext,
+        @RequestHeaders()
+        requestHeaders: Headers
+    ) {
+        const headersValidation = await headersSchema.safeParseAsync(requestHeaders.toJSON());
+
+        if (!headersValidation.success) {
+            return context.set(Keys.authState, undefined);
+        } else {
+            const {
+                authorization: { token }
+            } = headersValidation.data;
+
+            try {
+                const { account, credential } = await this.clientInstance.verifyToken({
+                    token: token
+                });
+
+                const authState: TAuthState = Object.freeze({
+                    account: account,
+                    credential: credential
+                });
+
+                return context.set(Keys.authState, authState);
+            } catch (error) {
+                console.error(error);
+                return context.set(Keys.authState, undefined);
+            }
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export type * from "./interfaces";
+
+export * from "./constants";
+export * from "./decorators";
+export * from "./entities";
+export * from "./instances";

package/src/instances/client.ts

@@ -0,0 +1,314 @@
+import type { TApiResponse } from "../interfaces/base";
+import type { IClient, TClientConfigs, TClientOptions } from "../interfaces/client.interface";
+
+import { SignJWT } from "jose";
+import { email } from "zod/v4";
+import { Enums } from "../constants";
+
+export class Client implements IClient {
+    readonly #baseUri = Enums.ETokenAudiences.SYSTEM;
+
+    private token: string | undefined;
+
+    /**
+     * Initialize BoolGuard client instance
+     * @param configs
+     * @param options
+     */
+    constructor(
+        private readonly configs: TClientConfigs,
+        private readonly options?: TClientOptions
+    ) {}
+
+    /**
+     * Sign JWT token with Ed25519 algorithm
+     * @returns
+     */
+    async signToken() {
+        try {
+            const rawKey = new Uint8Array(Buffer.from(this.configs.secretKey, "base64"));
+            const privateKey = await crypto.subtle.importKey(
+                "raw",
+                rawKey,
+                { name: "HMAC", hash: "SHA-512" },
+                false,
+                ["sign", "verify"]
+            );
+
+            const jwt = await new SignJWT({
+                tenantId: this.configs.tenantId,
+                appId: this.configs.appId,
+                modeId: this.configs.modeId,
+                iss: this.configs.tenantId,
+                aud: Enums.ETokenAudiences.SYSTEM
+            })
+                .setProtectedHeader({ alg: "HS512" })
+                .sign(privateKey);
+
+            this.token = jwt;
+
+            return jwt;
+        } catch (error) {
+            if (this.options?.logs) {
+                console.error("[BoolGuard] Sign token error:", error);
+            }
+
+            throw error;
+        }
+    }
+
+    /**
+     * Ping to BoolGuard service to check if the service is reachable
+     * This action should be done before any other actions.
+     * @returns
+     */
+    async ping() {
+        try {
+            const authToken = this.token || (await this.signToken());
+
+            const requestHeaders = new Headers();
+            requestHeaders.append("X-Tenant-ID", this.configs.tenantId);
+            requestHeaders.append("X-App-ID", this.configs.appId);
+            requestHeaders.append("X-Mode-ID", this.configs.modeId);
+            requestHeaders.append("Authorization", `Bearer ${authToken}`);
+
+            const response = await fetch(
+                `${this.#baseUri}/v${this.options?.version}/tenant-app-modes/ping`,
+                {
+                    method: "GET",
+                    headers: requestHeaders
+                }
+            );
+
+            if (!response.ok) {
+                throw await response.json();
+            }
+
+            return response.ok;
+        } catch (error) {
+            if (this.options?.logs) {
+                console.error("[BoolGuard] Ping error:", error);
+            }
+
+            return false;
+        }
+    }
+
+    /**
+     * Create a new plain account with custom account name
+     * @param args
+     * @returns
+     */
+    async createPlainAccount({
+        identity,
+        password,
+        metadata
+    }: Parameters<IClient["createPlainAccount"]>[number]): ReturnType<
+        IClient["createPlainAccount"]
+    > {
+        try {
+            const authToken = this.token || (await this.signToken());
+
+            const requestHeaders = new Headers();
+            requestHeaders.append("X-Tenant-ID", this.configs.tenantId);
+            requestHeaders.append("X-App-ID", this.configs.appId);
+            requestHeaders.append("X-Mode-ID", this.configs.modeId);
+            requestHeaders.append("Authorization", `Bearer ${authToken}`);
+            requestHeaders.append("Content-Type", "application/json");
+
+            const response = await fetch(
+                `${this.#baseUri}/v${this.options?.version}/tenant-app-mode-accounts`,
+                {
+                    method: "POST",
+                    headers: requestHeaders,
+                    body: JSON.stringify({
+                        data: {
+                            type: "plain",
+                            identity: identity,
+                            password: password,
+                            metadata: metadata
+                        }
+                    })
+                }
+            );
+
+            if (!response.ok) {
+                throw await response.json();
+            }
+
+            const { data } = (await response.json()) as TApiResponse<IClient["createPlainAccount"]>;
+
+            return Object.freeze({
+                account: data.account,
+                credential: data.credential
+            });
+        } catch (error) {
+            if (this.options?.logs) {
+                console.error("[BoolGuard] Create plain account error:", error);
+            }
+
+            throw error;
+        }
+    }
+
+    /**
+     * Create a new email account, this action will create email record and link to account
+     * with random account alias generated by system.
+     * @param args
+     */
+    async createEmailAccount({
+        identity,
+        password,
+        metadata
+    }: Parameters<IClient["createEmailAccount"]>[number]): ReturnType<
+        IClient["createEmailAccount"]
+    > {
+        try {
+            const authToken = this.token || (await this.signToken());
+
+            const requestHeaders = new Headers();
+            requestHeaders.append("X-Tenant-ID", this.configs.tenantId);
+            requestHeaders.append("X-App-ID", this.configs.appId);
+            requestHeaders.append("X-Mode-ID", this.configs.modeId);
+            requestHeaders.append("Authorization", `Bearer ${authToken}`);
+            requestHeaders.append("Content-Type", "application/json");
+
+            const response = await fetch(
+                `${this.#baseUri}/v${this.options?.version}/tenant-app-mode-accounts`,
+                {
+                    method: "POST",
+                    headers: requestHeaders,
+                    body: JSON.stringify({
+                        data: {
+                            type: "email",
+                            identity: identity,
+                            password: password,
+                            metadata: metadata
+                        }
+                    })
+                }
+            );
+
+            if (!response.ok) {
+                throw await response.json();
+            }
+
+            const { data } = (await response.json()) as TApiResponse<IClient["createEmailAccount"]>;
+
+            return Object.freeze({
+                account: data.account,
+                credential: data.credential
+            });
+        } catch (error) {
+            if (this.options?.logs) {
+                console.error("[BoolGuard] Create email account error:", error);
+            }
+
+            throw error;
+        }
+    }
+
+    /**
+     * Authenticate an account with account name and password
+     * This action will return account info and JWT token if successful
+     * @param param0
+     */
+    async authenticate({
+        identity,
+        password
+    }: Parameters<IClient["authenticate"]>[number]): ReturnType<IClient["authenticate"]> {
+        try {
+            const authToken = this.token || (await this.signToken());
+            const emailValidation = await email().safeParseAsync(identity);
+
+            const requestHeaders = new Headers();
+            requestHeaders.append("X-Tenant-ID", this.configs.tenantId);
+            requestHeaders.append("X-App-ID", this.configs.appId);
+            requestHeaders.append("X-Mode-ID", this.configs.modeId);
+            requestHeaders.append("Authorization", `Bearer ${authToken}`);
+            requestHeaders.append("Content-Type", "application/json");
+
+            const response = await fetch(
+                `${this.#baseUri}/v${this.options?.version}/tenant-app-mode-accounts/authenticate`,
+                {
+                    method: "POST",
+                    headers: requestHeaders,
+                    body: JSON.stringify({
+                        data: {
+                            type: !emailValidation.success ? "plain" : "email",
+                            identity: identity,
+                            password: password
+                        }
+                    })
+                }
+            );
+
+            if (!response.ok) {
+                throw await response.json();
+            }
+
+            const { data } = (await response.json()) as TApiResponse<IClient["authenticate"]>;
+
+            return Object.freeze({
+                account: data.account,
+                credential: data.credential,
+                token: data.token
+            });
+        } catch (error) {
+            if (this.options?.logs) {
+                console.error("[BoolGuard] Authenticate error:", error);
+            }
+
+            throw error;
+        }
+    }
+
+    /**
+     * Authenticate a token and return account info if token is valid
+     * @param param0
+     */
+    async verifyToken({
+        token
+    }: Parameters<IClient["verifyToken"]>[number]): ReturnType<IClient["verifyToken"]> {
+        try {
+            const authToken = this.token || (await this.signToken());
+
+            const requestHeaders = new Headers();
+            requestHeaders.append("X-Tenant-ID", this.configs.tenantId);
+            requestHeaders.append("X-App-ID", this.configs.appId);
+            requestHeaders.append("X-Mode-ID", this.configs.modeId);
+            requestHeaders.append("Authorization", `Bearer ${authToken}`);
+            requestHeaders.append("Content-Type", "application/json");
+
+            const response = await fetch(
+                `${this.#baseUri}/v${this.options?.version}/tenant-app-mode-accounts/verify`,
+                {
+                    method: "POST",
+                    headers: requestHeaders,
+                    body: JSON.stringify({
+                        data: {
+                            token: token
+                        }
+                    })
+                }
+            );
+
+            if (!response.ok) {
+                throw await response.json();
+            }
+
+            const { data } = (await response.json()) as TApiResponse<IClient["verifyToken"]>;
+
+            return Object.freeze({
+                account: data.account,
+                credential: data.credential
+            });
+        } catch (error) {
+            if (this.options?.logs) {
+                console.error("[BoolGuard] Verify token error:", error);
+            }
+
+            throw error;
+        }
+    }
+}