nucleus-core-ts 0.8.0

package/dist/src/Managers/Postgre/index.d.ts

@@ -0,0 +1,25 @@
+import { type QueryResultRow } from "pg";
+type PgResult<T = QueryResultRow> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+export type PgManagerConfig = {
+    database: string;
+    user: string;
+    password: string;
+    host: string;
+    port: number;
+    connectionTimeoutMillis?: number;
+};
+export declare class PostgreSQLManager {
+    private static instances;
+    private pool;
+    constructor(config?: PgManagerConfig);
+    execute<T extends QueryResultRow = QueryResultRow>(sql: string, params?: unknown[]): Promise<PgResult<T[]>>;
+    end(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Managers/Redis/index.d.ts

@@ -0,0 +1,33 @@
+type RedisResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+export type RedisConfig = {
+    url?: string;
+    host?: string;
+    port?: number;
+    withDapr?: boolean;
+    stateStoreName?: string;
+};
+export declare class RedisManager {
+    private static instance;
+    private store;
+    private directClient;
+    private useDapr;
+    constructor(config?: RedisConfig);
+    create<T>(key: string, value: T, ttlSeconds?: number): Promise<RedisResult<"OK">>;
+    read<T>(key: string): Promise<RedisResult<T | null>>;
+    update<T>(key: string, value: T, preserveTtl?: boolean): Promise<RedisResult<"OK">>;
+    remove(key: string): Promise<RedisResult<number>>;
+    exists(key: string): Promise<RedisResult<boolean>>;
+    keys(pattern: string): Promise<string[]>;
+    acquireLock(lockKey: string, ttlSeconds?: number): Promise<RedisResult<boolean>>;
+    releaseLock(lockKey: string): Promise<RedisResult<number>>;
+    waitForLock(lockKey: string, timeoutMs?: number, pollIntervalMs?: number): Promise<RedisResult<boolean>>;
+    getOrWait<T>(key: string, timeoutMs?: number, pollIntervalMs?: number): Promise<RedisResult<T | null>>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Managers/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./Dapr";
+export * from "./File";
+export * from "./Postgre";
+export * from "./Redis";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/Fingerprint/Generate/index.d.ts

@@ -0,0 +1,3 @@
+import type { DeviceFingerprint, DeviceFingerprintInput } from "../types";
+export declare const generateDeviceFingerprint: (input: DeviceFingerprintInput) => DeviceFingerprint;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/Fingerprint/Validate/index.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateFingerprintParams, ValidateFingerprintResult } from "../types";
+export declare const validateDeviceFingerprint: ({ savedFingerprint, requestIp, headers, }: ValidateFingerprintParams) => ValidateFingerprintResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/Fingerprint/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./Generate";
+export * from "./types";
+export * from "./utils";
+export * from "./Validate";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/Fingerprint/types.d.ts

@@ -0,0 +1,20 @@
+export type DeviceFingerprintInput = {
+    userAgent?: string;
+    ipAddress?: string;
+    extra?: Record<string, string | undefined>;
+};
+export type DeviceFingerprint = {
+    hash: string;
+    components: DeviceFingerprintInput;
+};
+export type ValidateFingerprintParams = {
+    savedFingerprint: DeviceFingerprint;
+    headers: Record<string, string>;
+    requestIp: string;
+};
+export type ValidateFingerprintResult = {
+    isValid: boolean;
+    reason?: string;
+    currentFingerprint: DeviceFingerprint;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/Services/Auth/Fingerprint/utils.d.ts

@@ -0,0 +1,3 @@
+export declare const normalize: (value?: string) => string;
+export declare const extractHeaderValue: (headers: Record<string, string>, key: string) => string | undefined;
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/Services/Auth/JWT/Decode/index.d.ts

@@ -0,0 +1,3 @@
+import type { DecodeResult } from "../types";
+export declare const decodeJWT: (token: string) => DecodeResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/JWT/Sign/index.d.ts

@@ -0,0 +1,3 @@
+import type { JWTHeader, SignOptions } from "../types";
+export declare const signJWT: (options: SignOptions, secret: string, algorithm?: JWTHeader["alg"]) => string;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/JWT/Verify/index.d.ts

@@ -0,0 +1,3 @@
+import type { VerifyResult } from "../types";
+export declare const verifyJWT: (token: string, secret: string) => VerifyResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/JWT/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./Decode";
+export * from "./Sign";
+export * from "./types";
+export * from "./Verify";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/JWT/types.d.ts

@@ -0,0 +1,38 @@
+export type Algorithm = "HS256" | "HS384" | "HS512";
+export type JWTHeader = {
+    alg: Algorithm;
+    typ: "JWT";
+};
+export type JWTPayload = {
+    sub: string;
+    iat: number;
+    exp: number;
+    iss?: string;
+    aud?: string;
+    jti?: string;
+    sessionId?: string;
+    [key: string]: unknown;
+};
+export type SignOptions = {
+    subject: string;
+    expiresInSeconds: number;
+    algorithm?: Algorithm;
+    issuer?: string;
+    audience?: string;
+    sessionId?: string;
+    jwtId?: string;
+    customClaims?: Record<string, unknown>;
+};
+export type VerifyResult = {
+    valid: true;
+    payload: JWTPayload;
+} | {
+    valid: false;
+    error: string;
+};
+export type DecodeResult = {
+    header: JWTHeader;
+    payload: JWTPayload;
+    signature: string;
+} | null;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/Services/Auth/JWT/utils.d.ts

@@ -0,0 +1,10 @@
+import type { JWTHeader, JWTPayload } from "./types";
+export declare const base64UrlEncode: (data: string | Buffer) => string;
+export declare const base64UrlDecode: (data: string) => string;
+export declare const createSignature: (data: string, secret: string, algorithm: JWTHeader["alg"]) => string;
+export declare const verifySignature: (data: string, signature: string, secret: string, algorithm: JWTHeader["alg"]) => boolean;
+export declare const encodeHeader: (header: JWTHeader) => string;
+export declare const encodePayload: (payload: JWTPayload) => string;
+export declare const decodeHeader: (encoded: string) => JWTHeader | null;
+export declare const decodePayload: (encoded: string) => JWTPayload | null;
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/Services/Auth/Password/Generate/index.d.ts

@@ -0,0 +1,3 @@
+import type { GeneratePasswordHashOptions, GeneratePasswordHashResult } from "../types";
+export declare const generatePasswordHash: (options: GeneratePasswordHashOptions) => GeneratePasswordHashResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/Password/Validate/index.d.ts

@@ -0,0 +1,3 @@
+import type { ValidatePasswordOptions, ValidatePasswordResult } from "../types";
+export declare const validatePassword: (options: ValidatePasswordOptions) => ValidatePasswordResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/Password/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Generate";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/Password/types.d.ts

@@ -0,0 +1,16 @@
+export type GeneratePasswordHashOptions = {
+    password: string;
+    keyLength?: number;
+};
+export type GeneratePasswordHashResult = {
+    hash: string;
+};
+export type ValidatePasswordOptions = {
+    password: string;
+    hash: string;
+    keyLength?: number;
+};
+export type ValidatePasswordResult = {
+    isValid: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/Services/Auth/RefreshToken/Delete/index.d.ts

@@ -0,0 +1,3 @@
+import type { DeleteRefreshTokenOptions } from "../types";
+export declare const deleteRefreshToken: (options: DeleteRefreshTokenOptions) => Promise<boolean>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/RefreshToken/Generate/index.d.ts

@@ -0,0 +1,11 @@
+import type { GenerateRefreshTokenOptions, RefreshTokenRecord } from "../types";
+export declare const generateRefreshToken: (options: GenerateRefreshTokenOptions) => Promise<{
+    success: false;
+    error: string;
+    record?: undefined;
+} | {
+    success: true;
+    record: RefreshTokenRecord;
+    error?: undefined;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/RefreshToken/Read/index.d.ts

@@ -0,0 +1,11 @@
+import type { ReadRefreshTokenOptions } from "../types";
+export declare const readRefreshToken: (options: ReadRefreshTokenOptions) => Promise<{
+    success: false;
+    error: string;
+    record?: undefined;
+} | {
+    success: true;
+    record: import("../types").RefreshTokenRecord;
+    error?: undefined;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/RefreshToken/Validate/index.d.ts

@@ -0,0 +1,11 @@
+import type { ValidateRefreshTokenOptions } from "../types";
+export declare const validateRefreshToken: (options: ValidateRefreshTokenOptions) => Promise<{
+    success: false;
+    error: string;
+    record?: undefined;
+} | {
+    success: true;
+    record: import("../types").RefreshTokenRecord;
+    error?: undefined;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/RefreshToken/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./Delete";
+export * from "./Generate";
+export * from "./Read";
+export * from "./Validate";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/RefreshToken/types.d.ts

@@ -0,0 +1,27 @@
+export type RefreshTokenRecord = {
+    token: string;
+    userId: string;
+    sessionId?: string;
+    createdAt: string;
+    expiresAt: string;
+    metadata?: Record<string, unknown>;
+};
+export type GenerateRefreshTokenOptions = {
+    userId: string;
+    sessionId?: string;
+    expiresInSeconds?: number;
+    metadata?: Record<string, unknown>;
+    jwtSecret: string;
+};
+export type ReadRefreshTokenOptions = {
+    token: string;
+    jwtSecret: string;
+};
+export type ValidateRefreshTokenOptions = {
+    token: string;
+    jwtSecret: string;
+};
+export type DeleteRefreshTokenOptions = {
+    token: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/Services/Auth/RefreshToken/utils.d.ts

@@ -0,0 +1,6 @@
+import type { RefreshTokenRecord } from "./types";
+export declare const DEFAULT_REFRESH_TTL_SECONDS: number;
+export declare const buildRefreshTokenKey: (token: string) => string;
+export declare const serializeRefreshToken: (record: RefreshTokenRecord) => string;
+export declare const deserializeRefreshToken: (data: string | null) => RefreshTokenRecord | null;
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/Services/Auth/Session/Issue/index.d.ts

@@ -0,0 +1,9 @@
+import type { IssueSessionOptions, IssueSessionResult } from "../types";
+export declare const issueSession: (options: IssueSessionOptions) => Promise<{
+    success: true;
+    data: IssueSessionResult;
+} | {
+    success: false;
+    error: string;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/Session/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Issue";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/Session/types.d.ts

@@ -0,0 +1,13 @@
+export type IssueSessionOptions = {
+    userId: string;
+    accessTokenTtlSeconds?: number;
+    jwtSecret: string;
+};
+export type IssueSessionResult = {
+    accessToken: string;
+    accessTokenExpiresAt: string;
+    refreshToken: string;
+    refreshExpiresAt: string;
+    sessionId: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/Services/Auth/SessionStore/Delete/index.d.ts

@@ -0,0 +1,3 @@
+import type { DeleteSessionOptions } from "../types";
+export declare const deleteSession: (options: DeleteSessionOptions) => Promise<boolean>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/SessionStore/Generate/index.d.ts

@@ -0,0 +1,11 @@
+import type { GenerateSessionOptions, SessionRecord } from "../types";
+export declare const generateSession: (options: GenerateSessionOptions) => Promise<{
+    success: false;
+    error: string;
+    session?: undefined;
+} | {
+    success: true;
+    session: SessionRecord;
+    error?: undefined;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/SessionStore/Read/index.d.ts

@@ -0,0 +1,3 @@
+import type { ReadSessionOptions } from "../types";
+export declare const readSession: (options: ReadSessionOptions) => Promise<import("..").SessionRecord | null>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/SessionStore/Update/index.d.ts

@@ -0,0 +1,24 @@
+import type { SessionRecord } from "../types";
+export type UpdateSessionOptions = {
+    sessionId: string;
+    updates: Partial<Omit<SessionRecord, "id" | "userId" | "createdAt">>;
+};
+export declare const updateSession: (options: UpdateSessionOptions) => Promise<{
+    success: false;
+    error: string;
+    session?: undefined;
+} | {
+    success: true;
+    session: SessionRecord;
+    error?: undefined;
+}>;
+export declare const updateLastActiveAt: (sessionId: string) => Promise<{
+    success: false;
+    error: string;
+    session?: undefined;
+} | {
+    success: true;
+    session: SessionRecord;
+    error?: undefined;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/SessionStore/Validate/index.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateSessionOptions, ValidateSessionResult } from "../types";
+export declare const validateSession: (options: ValidateSessionOptions) => Promise<ValidateSessionResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/SessionStore/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./Delete";
+export * from "./Generate";
+export * from "./Read";
+export * from "./types";
+export * from "./Update";
+export * from "./Validate";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Auth/SessionStore/types.d.ts

@@ -0,0 +1,59 @@
+import type { DeviceFingerprint } from "../Fingerprint/types";
+export type DeviceInfo = {
+    deviceName?: string;
+    deviceType?: "desktop" | "mobile" | "tablet" | "unknown";
+    browserName?: string;
+    browserVersion?: string;
+    osName?: string;
+    osVersion?: string;
+    ipAddress: string;
+    userAgent?: string;
+};
+export type SessionRecord = {
+    id: string;
+    userId: string;
+    createdAt: string;
+    expiresAt: string;
+    lastActiveAt: string;
+    clientMeta?: Record<string, unknown>;
+    fingerprintHash?: string;
+    deviceInfo?: DeviceInfo;
+    refreshTokenHash?: string;
+    loginMethod?: string;
+    rememberMe?: boolean;
+};
+export type GenerateSessionOptions = {
+    userId: string;
+    expiresInSeconds?: number;
+    clientMeta?: Record<string, unknown>;
+    fingerprintHash?: string;
+    sessionId?: string;
+    deviceInfo?: DeviceInfo;
+    refreshTokenHash?: string;
+    loginMethod?: string;
+    rememberMe?: boolean;
+};
+export type ValidateSessionOptions = {
+    sessionId: string;
+    jwtToken: string;
+    jwtSecret: string;
+    savedFingerprint?: DeviceFingerprint;
+    headers?: Record<string, string | undefined>;
+    requestIp?: string;
+};
+export type ValidateSessionResult = {
+    isValid: boolean;
+    reason?: string;
+    context?: {
+        userId: string;
+        sessionId: string;
+        fingerprintValid?: boolean;
+    };
+};
+export type ReadSessionOptions = {
+    sessionId: string;
+};
+export type DeleteSessionOptions = {
+    sessionId: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/Services/Auth/SessionStore/utils.d.ts

@@ -0,0 +1,6 @@
+import type { SessionRecord } from "./types";
+export declare const DEFAULT_EXPIRY_SECONDS: number;
+export declare const buildSessionKey: (sessionId: string) => string;
+export declare const serializeSession: (record: SessionRecord) => string;
+export declare const deserializeSession: (data: string | null) => SessionRecord | null;
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/Services/Auth/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./Fingerprint";
+export * from "./JWT";
+export * from "./Password";
+export * from "./RefreshToken";
+export * from "./Session";
+export * from "./SessionStore";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Authorization/ClaimSeeder/index.d.ts

@@ -0,0 +1,6 @@
+import type { NucleusTable } from "@types";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { Logger } from "../../Logger";
+import type { AuthorizationConfig, ClaimGenerationResult } from "../types";
+export declare function seedClaims(db: NodePgDatabase, schemaTables: Record<string, unknown>, schemaRelations: Record<string, unknown>, entities: NucleusTable[], config: AuthorizationConfig, logger: Logger): Promise<ClaimGenerationResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Authorization/GodminSetup/index.d.ts

@@ -0,0 +1,10 @@
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { Logger } from "../../Logger";
+import type { AuthorizationConfig } from "../types";
+export declare function setupGodmin(db: NodePgDatabase, schemaTables: Record<string, unknown>, config: AuthorizationConfig, logger: Logger): Promise<{
+    success: boolean;
+    userId?: string;
+    roleId?: string;
+}>;
+export declare function isGodminRole(roleName: string): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Authorization/Middleware/index.d.ts

@@ -0,0 +1,21 @@
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { Logger } from "../../Logger";
+import type { AuthorizationCheckResult, HttpMethod, ParsedScope, ResolvedScope } from "../types";
+interface CheckAuthorizationParams {
+    userId: string;
+    method: HttpMethod;
+    entity: string;
+    requestedFields?: string[];
+    requestedRelations?: string[];
+    db: NodePgDatabase;
+    schemaTables: Record<string, unknown>;
+    logger: Logger;
+    userData?: Record<string, unknown>;
+}
+export declare function parseScope(scope: string | null): ParsedScope;
+export declare function checkAuthorization(params: CheckAuthorizationParams): Promise<AuthorizationCheckResult>;
+export declare function filterResponseFields<T extends Record<string, unknown>>(data: T | T[], allowedFields?: string[]): Partial<T> | Partial<T>[];
+export declare function filterResponseRelations<T extends Record<string, unknown>>(data: T | T[], allowedRelations?: string[]): T | T[];
+export declare function applyScopeFilters(scopeFilters: ResolvedScope | undefined): Record<string, unknown> | undefined;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Authorization/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./ClaimSeeder";
+export * from "./GodminSetup";
+export * from "./Middleware";
+export * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/Services/Authorization/types.d.ts

@@ -0,0 +1,68 @@
+export interface AuthorizationConfig {
+    enabled: boolean;
+    autoSeedClaims: boolean;
+    skipTables: string[];
+    skipColumns: string[];
+    excludedPaths: string[];
+    publicPaths: string[];
+    godminEmail?: string;
+    godminPassword?: string;
+}
+export interface Claim {
+    id: string;
+    action: string;
+    description: string;
+    path: string;
+    method: string;
+}
+export interface RoleClaim {
+    id: string;
+    role_id: string;
+    claim_id: string;
+    scope: string | null;
+}
+export interface UserRole {
+    id: string;
+    user_id: string;
+    role_id: string;
+}
+export interface Role {
+    id: string;
+    name: string;
+    description: string | null;
+}
+export interface ClaimGenerationResult {
+    total: number;
+    created: number;
+    existing: number;
+    claims: string[];
+}
+export interface AuthorizationCheckResult {
+    authorized: boolean;
+    allowedFields?: string[];
+    allowedRelations?: string[];
+    scopeFilters?: Record<string, unknown>;
+    reason?: string;
+}
+export interface ParsedScope {
+    [key: string]: string;
+}
+export interface SelfReference {
+    field: string;
+}
+export interface ParsedScopeWithSelf {
+    [key: string]: string | SelfReference;
+}
+export interface ResolvedScope {
+    [key: string]: unknown;
+}
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface ClaimContext {
+    method: HttpMethod;
+    entity: string;
+    field?: string;
+    relation?: string;
+    relationField?: string;
+}
+export declare const DEFAULT_AUTHORIZATION_CONFIG: AuthorizationConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/Services/Captcha/index.d.ts

@@ -0,0 +1,15 @@
+import type { CaptchaDifficulty, CaptchaGenerateResult, CaptchaServiceDeps, CaptchaType, CaptchaValidateResult } from "./types";
+export declare class CaptchaService {
+    private redis;
+    private logger;
+    private config;
+    constructor(deps: CaptchaServiceDeps);
+    generate(type?: CaptchaType, difficulty?: CaptchaDifficulty, ipAddress?: string): Promise<CaptchaGenerateResult>;
+    validate(challengeId: string, userAnswer: string): Promise<CaptchaValidateResult>;
+    invalidate(challengeId: string): Promise<void>;
+    isEnabled(): boolean;
+    private checkRateLimit;
+    private incrementRateLimit;
+}
+export * from "./types";
+//# sourceMappingURL=index.d.ts.map