@3d-outlet/passport 1.0.0

package/README.md

@@ -0,0 +1,171 @@
+<div align="center">
+
+# 🔑 @3d-outlet/passport
+
+**Token-based Authentication Module for 3D OUTLET Microservices**
+
+[![npm version](https://img.shields.io/npm/v/@3d-outlet/passport?style=for-the-badge)](https://www.npmjs.com/package/@3d-outlet/passport)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg?style=for-the-badge)](https://opensource.org/licenses/ISC)
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🛡️ **Secure Token Generation** - Creates HMAC-based tokens considering `userId`, `issuedAt`, and `expiresAt`.
+- 🔑 **Reliable Token Verification** - Authenticates and validates token expiration using constant-time comparison.
+- 🚀 **NestJS Integration** - Easy integration into NestJS applications using `PassportModule`.
+- 🔄 **Flexible Configuration** - Supports synchronous and asynchronous module configuration.
+- 🔐 **Encoding and Decoding** - Built-in utilities for Base64 URL encoding/decoding and cryptographic operations.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @3d-outlet/passport
+# or
+pnpm add @3d-outlet/passport
+# or
+yarn add @3d-outlet/passport
+# or
+bun add @3d-outlet/passport
+```
+
+---
+
+## 🚀 Quick Start
+
+### Module Registration
+
+#### Synchronous Registration
+
+```typescript
+import { Module } from '@nestjs/common'
+import { PassportModule } from '@3d-outlet/passport'
+
+@Module({
+  imports: [
+    PassportModule.register({
+      secretKey: 'YOUR_VERY_SECRET_KEY', // Replace with your secret key
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+#### Asynchronous Registration
+
+```typescript
+import { Module } from '@nestjs/common'
+import { PassportModule } from '@3d-outlet/passport'
+import { ConfigModule, ConfigService } from '@nestjs/config'
+
+@Module({
+  imports: [
+    PassportModule.registerAsync({
+      imports: [ConfigModule],
+      useFactory: async (configService: ConfigService) => ({
+        secretKey: configService.get<string>('PASSPORT_SECRET_KEY'),
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Using `PassportService`
+
+```typescript
+import { Injectable } from '@nestjs/common'
+import { PassportService } from '@3d-outlet/passport'
+
+@Injectable()
+export class AuthService {
+  constructor(private readonly passportService: PassportService) {}
+
+  async login(userId: string) {
+    const ttl = 3600 // Token expiration in seconds (1 hour)
+    const token = this.passportService.generate(userId, ttl)
+    return { token }
+  }
+
+  async verifyToken(token: string) {
+    const result = this.passportService.verify(token)
+    if (!result.valid) {
+      console.error('Invalid token:', result.reason)
+      return null
+    }
+    console.log('User:', result.userId)
+    return result.userId
+  }
+}
+```
+
+---
+
+## 📁 Project Structure
+
+```
+passport/
+├── lib/                      # TypeScript source files
+│   ├── constants/            # Passport module constants
+│   ├── interfaces/           # Interfaces for module options and tokens
+│   ├── utils/                # Utility functions (Base64, Crypto)
+│   ├── passport.module.ts    # Main NestJS Passport module
+│   ├── passport.providers.ts # Module configuration providers
+│   └── passport.service.ts   # Service for token generation and verification
+└── dist/                     # Compiled JavaScript (after build)
+```
+
+---
+
+## 🛠️ Development
+
+### Prerequisites
+
+- **Node.js**: >= 16.0.0
+- **TypeScript**: ^5.9.3
+
+### Building the Package
+
+```bash
+# Install dependencies
+npm install
+# или
+pnpm install
+# или
+bun install
+
+# Build TypeScript
+npm run build
+```
+
+---
+
+## 📝 License
+
+ISC © [TeaCoder](mailto:admin@teacoder.ru) & [Ilnaz Mingaleev](mailto:development@teamkaif.com)
+
+---
+
+## 👨‍💻 Authors
+
+**TeaCoder (Vadim)**
+
+- Email: [admin@teacoder.ru](mailto:admin@teacoder.ru)
+
+**Ilnaz Mingaleev**
+
+- Email: [development@teamkaif.com](mailto:development@teamkaif.com)
+
+---
+
+<div align="center">
+
+**Made with ❤️ for the 3D OUTLET project (private repo)**  
+Internal use only.
+
+</div>

package/dist/constants/index.d.ts

@@ -0,0 +1 @@
+export * from './passport.constants';

package/dist/constants/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./passport.constants"), exports);

package/dist/constants/passport.constants.d.ts

@@ -0,0 +1 @@
+export declare const PASSPORT_OPTIONS: unique symbol;

package/dist/constants/passport.constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PASSPORT_OPTIONS = void 0;
+exports.PASSPORT_OPTIONS = Symbol('PassportOptions');

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './interfaces';
+export * from './passport.module';
+export * from './passport.service';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./interfaces"), exports);
+__exportStar(require("./passport.module"), exports);
+__exportStar(require("./passport.service"), exports);

package/dist/interfaces/index.d.ts

@@ -0,0 +1,3 @@
+export * from './passport-options.interface';
+export * from './passport-async-options.interface';
+export * from './token.interface';

package/dist/interfaces/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./passport-options.interface"), exports);
+__exportStar(require("./passport-async-options.interface"), exports);
+__exportStar(require("./token.interface"), exports);

package/dist/interfaces/passport-async-options.interface.d.ts

@@ -0,0 +1,6 @@
+import type { FactoryProvider, ModuleMetadata } from '@nestjs/common';
+import type { PassportOptions } from './passport-options.interface';
+export interface PassportAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    useFactory: (...args: any[]) => Promise<PassportOptions> | PassportOptions;
+    inject?: FactoryProvider['inject'];
+}

package/dist/interfaces/passport-async-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interfaces/passport-options.interface.d.ts

@@ -0,0 +1,3 @@
+export interface PassportOptions {
+    secretKey: string;
+}

package/dist/interfaces/passport-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,8 @@
+export interface TokenPayload {
+    sub: string | number;
+}
+export interface VerifyResult {
+    valid: boolean;
+    reason?: string;
+    userId?: string;
+}

package/dist/interfaces/token.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/passport.module.d.ts

@@ -0,0 +1,6 @@
+import { type DynamicModule } from '@nestjs/common';
+import type { PassportAsyncOptions, PassportOptions } from './interfaces';
+export declare class PassportModule {
+    static register(options: PassportOptions): DynamicModule;
+    static registerAsync(options: PassportAsyncOptions): DynamicModule;
+}

package/dist/passport.module.js

@@ -0,0 +1,38 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var PassportModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PassportModule = void 0;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("./constants");
+const passport_providers_1 = require("./passport.providers");
+const passport_service_1 = require("./passport.service");
+let PassportModule = PassportModule_1 = class PassportModule {
+    static register(options) {
+        const optionsProvider = (0, passport_providers_1.createPassportOptionsProvider)(options);
+        return {
+            module: PassportModule_1,
+            providers: [optionsProvider, passport_service_1.PassportService],
+            exports: [passport_service_1.PassportService, constants_1.PASSPORT_OPTIONS]
+        };
+    }
+    static registerAsync(options) {
+        const optionsProvider = (0, passport_providers_1.createPassportAsyncOptionsProvider)(options);
+        return {
+            module: PassportModule_1,
+            imports: options.imports ?? [],
+            providers: [optionsProvider, passport_service_1.PassportService],
+            exports: [passport_service_1.PassportService, constants_1.PASSPORT_OPTIONS]
+        };
+    }
+};
+exports.PassportModule = PassportModule;
+exports.PassportModule = PassportModule = PassportModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], PassportModule);

package/dist/passport.providers.d.ts

@@ -0,0 +1,4 @@
+import type { Provider } from '@nestjs/common';
+import type { PassportAsyncOptions, PassportOptions } from './interfaces';
+export declare function createPassportOptionsProvider(options: PassportOptions): Provider;
+export declare function createPassportAsyncOptionsProvider(options: PassportAsyncOptions): Provider;

package/dist/passport.providers.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPassportOptionsProvider = createPassportOptionsProvider;
+exports.createPassportAsyncOptionsProvider = createPassportAsyncOptionsProvider;
+const constants_1 = require("./constants");
+function createPassportOptionsProvider(options) {
+    return {
+        provide: constants_1.PASSPORT_OPTIONS,
+        useValue: Object.freeze({ ...options })
+    };
+}
+function createPassportAsyncOptionsProvider(options) {
+    return {
+        provide: constants_1.PASSPORT_OPTIONS,
+        useFactory: async (...args) => {
+            const resolved = await options.useFactory(...args);
+            if (!resolved || typeof resolved.secretKey !== 'string') {
+                throw new Error('[PassportModule] "secretKey" is required and must be a string');
+            }
+            return Object.freeze({ ...resolved });
+        },
+        inject: options.inject ?? []
+    };
+}

package/dist/passport.service.d.ts

@@ -0,0 +1,21 @@
+import { PassportOptions } from './interfaces';
+export declare class PassportService {
+    private readonly options;
+    private readonly SECRET_KEY;
+    private static readonly HMAC_DOMAIN;
+    private static readonly INTERNAL_SEP;
+    constructor(options: PassportOptions);
+    generate(userId: string, ttl: number): string;
+    verify(token: string): {
+        valid: boolean;
+        reason: string;
+        userId?: undefined;
+    } | {
+        valid: boolean;
+        userId: string;
+        reason?: undefined;
+    };
+    private now;
+    private serialize;
+    private computeHmac;
+}

package/dist/passport.service.js

@@ -0,0 +1,72 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var PassportService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PassportService = void 0;
+const common_1 = require("@nestjs/common");
+const crypto_1 = require("crypto");
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+let PassportService = class PassportService {
+    static { PassportService_1 = this; }
+    options;
+    SECRET_KEY;
+    static HMAC_DOMAIN = 'PassportTokenAuth/v1';
+    static INTERNAL_SEP = '|';
+    constructor(options) {
+        this.options = options;
+        this.SECRET_KEY = options.secretKey;
+    }
+    generate(userId, ttl) {
+        const issuedAt = this.now();
+        const expiresAt = issuedAt + ttl;
+        const userPart = (0, utils_1.base64UrlEncode)(userId);
+        const iatPart = (0, utils_1.base64UrlEncode)(String(issuedAt));
+        const expPart = (0, utils_1.base64UrlEncode)(String(expiresAt));
+        const serialized = this.serialize(userPart, iatPart, expPart);
+        const mac = this.computeHmac(this.SECRET_KEY, serialized);
+        return `${userPart}.${iatPart}.${expPart}.${mac}`;
+    }
+    verify(token) {
+        const parts = token.split('.');
+        if (parts.length !== 4)
+            return { valid: false, reason: 'Invalid format' };
+        const [userPart, iatPart, expPart, mac] = parts;
+        const serialized = this.serialize(userPart, iatPart, expPart);
+        const expectedMac = this.computeHmac(this.SECRET_KEY, serialized);
+        if (!(0, utils_1.constantTimeEqual)(expectedMac, mac))
+            return { valid: false, reason: 'Invalid signature' };
+        const expNumber = Number((0, utils_1.base64UrlDecode)(expPart));
+        if (!Number.isFinite(expNumber))
+            return { valid: false, reason: 'Error' };
+        if (this.now() > expNumber)
+            return { valid: false, reason: 'Expired' };
+        return { valid: true, userId: (0, utils_1.base64UrlDecode)(userPart) };
+    }
+    now() {
+        return Math.floor(Date.now() / 1000);
+    }
+    serialize(user, iat, exp) {
+        return [PassportService_1.HMAC_DOMAIN, user, iat, exp].join(PassportService_1.INTERNAL_SEP);
+    }
+    computeHmac(secretKey, data) {
+        return (0, crypto_1.createHmac)('sha256', secretKey).update(data).digest('hex');
+    }
+};
+exports.PassportService = PassportService;
+exports.PassportService = PassportService = PassportService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.PASSPORT_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], PassportService);

package/dist/utils/base64.d.ts

@@ -0,0 +1,2 @@
+export declare function base64UrlEncode(buf: Buffer | string): string;
+export declare function base64UrlDecode(str: string): string;

package/dist/utils/base64.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.base64UrlEncode = base64UrlEncode;
+exports.base64UrlDecode = base64UrlDecode;
+function base64UrlEncode(buf) {
+    const s = typeof buf === 'string' ? Buffer.from(buf) : buf;
+    return s
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+function base64UrlDecode(str) {
+    str = str.replace(/-/g, '+').replace(/_/g, '/');
+    while (str.length % 4)
+        str += '=';
+    return Buffer.from(str, 'base64').toString();
+}

package/dist/utils/crypto.d.ts

@@ -0,0 +1 @@
+export declare function constantTimeEqual(a: string, b: string): boolean;

package/dist/utils/crypto.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constantTimeEqual = constantTimeEqual;
+const crypto_1 = require("crypto");
+function constantTimeEqual(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length)
+        return false;
+    return (0, crypto_1.timingSafeEqual)(bufA, bufB);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './base64';
+export * from './crypto';

package/dist/utils/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base64"), exports);
+__exportStar(require("./crypto"), exports);

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@3d-outlet/passport",
+	"version": "1.0.0",
+	"description": "Lightweight Face3D authentication library",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"format": "prettier --write \"lib/**/*.ts\""
+	},
+	"keywords": [],
+	"author": "",
+	"license": "ISC",
+	"type": "commonjs",
+	"devDependencies": {
+		"@3d-outlet/core": "^1.0.2",
+		"@types/node": "^24.10.1",
+		"prettier": "^3.7.3",
+		"typescript": "^5.9.3"
+	},
+	"dependencies": {
+		"@nestjs/common": "^11.1.9",
+		"@nestjs/core": "^11.1.9",
+		"reflect-metadata": "^0.2.2",
+		"txjs": "^0.1.1"
+	}
+}