@plyaz/auth 1.0.0

package/.github/pull_request_template.md

@@ -0,0 +1,71 @@
+# Pull Request Template
+
+## Jira Ticket
+
+- **Ticket**: [PLYENG-XXX](https://plyaz.atlassian.net/browse/PLYAZ-XXX)
+- **Epic**: [PLYENG-XXX](https://plyaz.atlassian.net/browse/PLYAZ-XXX) (if applicable)
+
+## Type of Change
+
+- [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
+- [ ] ✨ New feature (non-breaking change that adds functionality)
+- [ ] 💥 Breaking change (fix or feature with API changes or that would cause existing functionality to not work as expected)
+- [ ] 🔨 Refactoring (code improvement with no functional changes)
+- [ ] 📚 Documentation update
+- [ ] 🧪 Test update
+- [ ] 🛠️ Build/CI update
+- [ ] 🧹 Chore (dependency updates, maintenance tasks, etc.)
+
+## Approval Checklist
+
+All pull requests must satisfy the following criteria before being considered for approval:
+
+### 1. Tests
+
+- [ ] New tests added for all new functionality
+- [ ] Minimum 90% test coverage for modified code
+- [ ] All existing tests passing without failures
+- [ ] Edge cases and error conditions properly tested
+
+### 2. Documentation
+
+- [ ] Code is properly documented with JSDoc comments
+- [ ] README files updated if necessary
+- [ ] Architecture documentation updated for structural changes before any code written
+- [ ] Storybook entries created/updated for UI components
+- [ ] API endpoints documented if modified or added
+- [ ] Ensure that the architecture has to be updated or created on the respective stack:
+  - [Backend](https://plyaz.atlassian.net/wiki/spaces/SD/folder/950466)
+  - [Frontend](https://plyaz.atlassian.net/wiki/spaces/SD/folder/655573)
+  - [Blockchain](https://plyaz.atlassian.net/wiki/spaces/SD/folder/753881)
+  - [Infrastructure](https://plyaz.atlassian.net/wiki/spaces/SD/folder/4096013)
+
+### 3. Quality
+
+- [ ] No linting errors or warnings (ESLint/TSLint)
+- [ ] Proper code formatting (Prettier)
+- [ ] TypeScript types properly defined and used
+- [ ] No code smells or anti-patterns
+- [ ] Adherence to project coding standards
+- [ ] Responsive design for frontend components
+
+### 4. Review
+
+- [ ] At least one approval from another developer
+- [ ] All review comments addressed with changes or explanations
+- [ ] Critical changes require architect approval
+- [ ] Security-sensitive changes require CTO approval
+
+### 5. Dependencies
+
+- [ ] No unnecessary dependencies added
+- [ ] Dependencies audited for security vulnerabilities
+- [ ] Package versions follow our version policy
+- [ ] Impact on bundle size assessed for frontend dependencies
+
+### 6. Performance
+
+- [ ] No obvious performance issues introduced
+- [ ] Database queries optimized for efficiency
+- [ ] Frontend components optimized for rendering performance
+- [ ] API endpoints respond within expected timeframes

package/.github/workflows/deploy.yml

@@ -0,0 +1,9 @@
+name: Install + Build + Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build-deploy:
+    uses: Plyaz-Official/devtools/.github/workflows/deploy.yml@main
+    secrets: inherit

package/.github/workflows/publish.yml

@@ -0,0 +1,14 @@
+name: Publish Package
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write         # Required for pushing version bumps and tags
+  packages: write         # Required for publishing packages  
+  pull-requests: read     # Required for reading PR information
+
+jobs:
+  publish:
+    uses: Plyaz-Official/devtools/.github/workflows/publish.yml@main
+    secrets: inherit

package/.github/workflows/security.yml

@@ -0,0 +1,20 @@
+name: Security
+on:
+  push:
+    branches: [main, dev, staging]
+  pull_request:
+    branches: [main, dev, staging]
+
+permissions:
+  contents: read
+  pull-requests: write      # Required for posting dependency review comments
+  security-events: write    # Required for OSV-Scanner SARIF uploads
+  actions: read            # Required for OSV-Scanner
+
+jobs:
+  security:
+    uses: Plyaz-Official/devtools/.github/workflows/security.yml@main
+    with:
+      skip_osv_scan: true
+      dependency_review: false
+    secrets: inherit

package/README.md

@@ -0,0 +1,89 @@
+# @plyaz/auth
+
+A shared authentication package for the Plyaz ecosystem. This library centralizes core authentication strategies, provider integrations, and access control logic, ensuring that all applications within our monorepo share a single, consistent source of truth for user sessions and permissions.
+
+## 📦 Installation
+
+```bash
+pnpm add @plyaz/auth
+```
+
+## 🚀 What's Included
+
+### Core Features
+
+- **Authentication Strategies** - Support for multiple authentication flows, including email/password, social logins, and token-based authentication (JWT, API keys).
+- **Provider Abstractions** - Standardized interfaces for integrating with external providers like Clerk, OAuth services, and other third-party authentication platforms.
+- **Role-Based Access Control (RBAC)** - A robust system for managing user roles and permissions, enabling granular control over application features.
+- **Session Management** - Secure and unified session handling across all Plyaz applications.
+- **Ecosystem Integration** - Seamlessly integrates with @plyaz/types, @plyaz/config, and other shared packages.
+
+## Development
+
+### Setup
+
+Install dependencies and run the basic checks:
+
+```bash
+pnpm install
+pnpm lint
+pnpm test
+```
+
+### Build
+
+Compile the library to the dist folder:
+
+```bash
+pnpm build
+```
+
+For a watch mode during development:
+
+```bash
+pnpm dev
+```
+
+### Linting & Formatting
+
+Run the ESLint rules and apply automatic fixes:
+
+```bash
+pnpm lint
+pnpm lint:fix
+```
+
+Check or apply Prettier formatting:
+
+```bash
+pnpm format:check
+pnpm format
+```
+
+### Tests
+
+Execute the test suite once:
+
+```bash
+pnpm test
+```
+
+Watch tests as you work:
+
+```bash
+pnpm test:watch
+```
+
+Generate coverage information:
+
+```bash
+pnpm test:coverage
+```
+
+## Relationship to Plyaz-Official/types
+
+Type definitions for authentication values, like User, Role, and Permission, live in [Plyaz-Official/types](https://github.com/Plyaz-Official/types). Installing @plyaz/types alongside this package provides strongly typed access to each exported constant and type.
+
+## About this repository
+
+This package was scaffolded from the internal package-template and relies on [@plyaz/devtools](https://www.npmjs.com/package/@plyaz/devtools) for shared TypeScript, ESLint, Prettier, and Vitest configuration.

package/commits.txt

@@ -0,0 +1,5 @@
+- chore: Add types (usmangq12)
+- chore: Fixed types issues (usmangq12)
+- chore: Fixed types issues (usmangq12)
+- chore: Add all required dev dependencies (usmangq12)
+- chore: Add eslint plugin (usmangq12)

package/dist/common/index.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+var config = require('@plyaz/config');
+
+// @plyaz package - Built with tsup
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function generateRandomString(length = 32) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+__name(generateRandomString, "generateRandomString");
+function generateSecureId() {
+  return `${Date.now()}_${generateRandomString(config.NUMERIX.SIXTEEN)}`;
+}
+__name(generateSecureId, "generateSecureId");
+function sleep(ms) {
+  return new Promise((resolve) => globalThis.setTimeout(resolve, ms));
+}
+__name(sleep, "sleep");
+function maskSensitiveData(data, sensitiveFields = ["password", "token", "secret"]) {
+  if (typeof data !== "object" || data === null) {
+    return data;
+  }
+  const masked = { ...data };
+  const four = 4;
+  for (const field of sensitiveFields) {
+    if (field in masked) {
+      const value = masked[field];
+      if (typeof value === "string" && value.length > 0) {
+        masked[field] = value.substring(0, four) + "*".repeat(Math.max(0, value.length - four));
+      }
+    }
+  }
+  return masked;
+}
+__name(maskSensitiveData, "maskSensitiveData");
+
+exports.generateRandomString = generateRandomString;
+exports.generateSecureId = generateSecureId;
+exports.maskSensitiveData = maskSensitiveData;
+exports.sleep = sleep;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/common/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/common/utils/index.ts"],"names":["NUMERIX"],"mappings":";;;;;;;AAgBO,SAAS,oBAAA,CAAqB,SAAiB,EAAA,EAAY;AAChE,EAAA,MAAM,KAAA,GAAQ,gEAAA;AACd,EAAA,IAAI,MAAA,GAAS,EAAA;AACb,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,MAAA,EAAQ,CAAA,EAAA,EAAK;AAC/B,IAAA,MAAA,IAAU,KAAA,CAAM,OAAO,IAAA,CAAK,KAAA,CAAM,KAAK,MAAA,EAAO,GAAI,KAAA,CAAM,MAAM,CAAC,CAAA;AAAA,EACjE;AACA,EAAA,OAAO,MAAA;AACT;AAPgB,MAAA,CAAA,oBAAA,EAAA,sBAAA,CAAA;AAiBT,SAAS,gBAAA,GAA2B;AACzC,EAAA,OAAO,CAAA,EAAG,KAAK,GAAA,EAAK,IAAI,oBAAA,CAAqBA,cAAA,CAAQ,OAAO,CAAC,CAAA,CAAA;AAC/D;AAFgB,MAAA,CAAA,gBAAA,EAAA,kBAAA,CAAA;AAaT,SAAS,MAAM,EAAA,EAA2B;AAC/C,EAAA,OAAO,IAAI,OAAA,CAAQ,CAAA,OAAA,KAAW,WAAW,UAAA,CAAW,OAAA,EAAS,EAAE,CAAC,CAAA;AAClE;AAFgB,MAAA,CAAA,KAAA,EAAA,OAAA,CAAA;AAeT,SAAS,kBACd,IAAA,EACA,eAAA,GAA4B,CAAC,UAAA,EAAY,OAAA,EAAS,QAAQ,CAAA,EACjD;AACT,EAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,IAAA,KAAS,IAAA,EAAM;AAC7C,IAAA,OAAO,IAAA;AAAA,EACT;AAGA,EAAA,MAAM,MAAA,GAAiC,EAAE,GAAI,IAAA,EAAgC;AAC7E,EAAA,MAAM,IAAA,GAAQ,CAAA;AACd,EAAA,KAAA,MAAW,SAAS,eAAA,EAAiB;AACnC,IAAA,IAAI,SAAS,MAAA,EAAQ;AACnB,MAAA,MAAM,KAAA,GAAQ,OAAO,KAAK,CAAA;AAC1B,MAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,CAAM,SAAS,CAAA,EAAG;AACjD,QAAA,MAAA,CAAO,KAAK,CAAA,GAAI,KAAA,CAAM,SAAA,CAAU,GAAG,IAAI,CAAA,GAAI,GAAA,CAAI,MAAA,CAAO,KAAK,GAAA,CAAI,CAAA,EAAG,KAAA,CAAM,MAAA,GAAS,IAAI,CAAC,CAAA;AAAA,MACxF;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;AArBgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA","file":"index.cjs","sourcesContent":["/**\n * @fileoverview Common utility functions for @plyaz/auth\n * @module @plyaz/auth/common/utils\n */\n\nimport { NUMERIX } from \"@plyaz/config\";\n\n/**\n * Generate a random string of specified length using alphanumeric characters\n * @param length - Length of the random string (default: 32)\n * @returns Random alphanumeric string\n * @example\n * ```typescript\n * const randomId = generateRandomString(16); // \"a1B2c3D4e5F6g7H8\"\n * ```\n */\nexport function generateRandomString(length: number = 32): string {\n  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';\n  let result = '';\n  for (let i = 0; i < length; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length));\n  }\n  return result;\n}\n\n/**\n * Generate a cryptographically secure random ID with timestamp prefix\n * @returns Unique identifier with timestamp and random suffix\n * @example\n * ```typescript\n * const id = generateSecureId(); // \"1703123456789_a1B2c3D4e5F6g7H8\"\n * ```\n */\nexport function generateSecureId(): string {\n  return `${Date.now()}_${generateRandomString(NUMERIX.SIXTEEN)}`;\n}\n\n/**\n * Sleep for specified milliseconds (async delay)\n * @param ms - Milliseconds to sleep\n * @returns Promise that resolves after the delay\n * @example\n * ```typescript\n * await sleep(1000); // Wait 1 second\n * ```\n */\nexport function sleep(ms: number): Promise<void> {\n  return new Promise(resolve => globalThis.setTimeout(resolve, ms));\n}\n\n/**\n * Mask sensitive data fields for safe logging\n * @param data - Object containing potentially sensitive data\n * @param sensitiveFields - Array of field names to mask (default: ['password', 'token', 'secret'])\n * @returns Object with sensitive fields masked\n * @example\n * ```typescript\n * const masked = maskSensitiveData({ email: 'user@example.com', password: 'secret123' });\n * // Result: { email: 'user@example.com', password: 'secr*****' }\n * ```\n */\nexport function maskSensitiveData(\n  data: unknown,\n  sensitiveFields: string[] = ['password', 'token', 'secret']\n): unknown {\n  if (typeof data !== 'object' || data === null) {\n    return data;\n  }\n\n  // Type assertion to allow indexing by string\n  const masked: Record<string, string> = { ...(data as Record<string, string>) };\n  const four  = 4;\n  for (const field of sensitiveFields) {\n    if (field in masked) {\n      const value = masked[field];\n      if (typeof value === 'string' && value.length > 0) {\n        masked[field] = value.substring(0, four) + '*'.repeat(Math.max(0, value.length - four));\n      }\n    }\n  }\n  \n  return masked;\n}\n\n"]}

package/dist/common/index.mjs

@@ -0,0 +1,43 @@
+import { NUMERIX } from '@plyaz/config';
+
+// @plyaz package - Built with tsup
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function generateRandomString(length = 32) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+__name(generateRandomString, "generateRandomString");
+function generateSecureId() {
+  return `${Date.now()}_${generateRandomString(NUMERIX.SIXTEEN)}`;
+}
+__name(generateSecureId, "generateSecureId");
+function sleep(ms) {
+  return new Promise((resolve) => globalThis.setTimeout(resolve, ms));
+}
+__name(sleep, "sleep");
+function maskSensitiveData(data, sensitiveFields = ["password", "token", "secret"]) {
+  if (typeof data !== "object" || data === null) {
+    return data;
+  }
+  const masked = { ...data };
+  const four = 4;
+  for (const field of sensitiveFields) {
+    if (field in masked) {
+      const value = masked[field];
+      if (typeof value === "string" && value.length > 0) {
+        masked[field] = value.substring(0, four) + "*".repeat(Math.max(0, value.length - four));
+      }
+    }
+  }
+  return masked;
+}
+__name(maskSensitiveData, "maskSensitiveData");
+
+export { generateRandomString, generateSecureId, maskSensitiveData, sleep };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/common/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/common/utils/index.ts"],"names":[],"mappings":";;;;;AAgBO,SAAS,oBAAA,CAAqB,SAAiB,EAAA,EAAY;AAChE,EAAA,MAAM,KAAA,GAAQ,gEAAA;AACd,EAAA,IAAI,MAAA,GAAS,EAAA;AACb,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,MAAA,EAAQ,CAAA,EAAA,EAAK;AAC/B,IAAA,MAAA,IAAU,KAAA,CAAM,OAAO,IAAA,CAAK,KAAA,CAAM,KAAK,MAAA,EAAO,GAAI,KAAA,CAAM,MAAM,CAAC,CAAA;AAAA,EACjE;AACA,EAAA,OAAO,MAAA;AACT;AAPgB,MAAA,CAAA,oBAAA,EAAA,sBAAA,CAAA;AAiBT,SAAS,gBAAA,GAA2B;AACzC,EAAA,OAAO,CAAA,EAAG,KAAK,GAAA,EAAK,IAAI,oBAAA,CAAqB,OAAA,CAAQ,OAAO,CAAC,CAAA,CAAA;AAC/D;AAFgB,MAAA,CAAA,gBAAA,EAAA,kBAAA,CAAA;AAaT,SAAS,MAAM,EAAA,EAA2B;AAC/C,EAAA,OAAO,IAAI,OAAA,CAAQ,CAAA,OAAA,KAAW,WAAW,UAAA,CAAW,OAAA,EAAS,EAAE,CAAC,CAAA;AAClE;AAFgB,MAAA,CAAA,KAAA,EAAA,OAAA,CAAA;AAeT,SAAS,kBACd,IAAA,EACA,eAAA,GAA4B,CAAC,UAAA,EAAY,OAAA,EAAS,QAAQ,CAAA,EACjD;AACT,EAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,IAAA,KAAS,IAAA,EAAM;AAC7C,IAAA,OAAO,IAAA;AAAA,EACT;AAGA,EAAA,MAAM,MAAA,GAAiC,EAAE,GAAI,IAAA,EAAgC;AAC7E,EAAA,MAAM,IAAA,GAAQ,CAAA;AACd,EAAA,KAAA,MAAW,SAAS,eAAA,EAAiB;AACnC,IAAA,IAAI,SAAS,MAAA,EAAQ;AACnB,MAAA,MAAM,KAAA,GAAQ,OAAO,KAAK,CAAA;AAC1B,MAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,CAAM,SAAS,CAAA,EAAG;AACjD,QAAA,MAAA,CAAO,KAAK,CAAA,GAAI,KAAA,CAAM,SAAA,CAAU,GAAG,IAAI,CAAA,GAAI,GAAA,CAAI,MAAA,CAAO,KAAK,GAAA,CAAI,CAAA,EAAG,KAAA,CAAM,MAAA,GAAS,IAAI,CAAC,CAAA;AAAA,MACxF;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;AArBgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA","file":"index.mjs","sourcesContent":["/**\n * @fileoverview Common utility functions for @plyaz/auth\n * @module @plyaz/auth/common/utils\n */\n\nimport { NUMERIX } from \"@plyaz/config\";\n\n/**\n * Generate a random string of specified length using alphanumeric characters\n * @param length - Length of the random string (default: 32)\n * @returns Random alphanumeric string\n * @example\n * ```typescript\n * const randomId = generateRandomString(16); // \"a1B2c3D4e5F6g7H8\"\n * ```\n */\nexport function generateRandomString(length: number = 32): string {\n  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';\n  let result = '';\n  for (let i = 0; i < length; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length));\n  }\n  return result;\n}\n\n/**\n * Generate a cryptographically secure random ID with timestamp prefix\n * @returns Unique identifier with timestamp and random suffix\n * @example\n * ```typescript\n * const id = generateSecureId(); // \"1703123456789_a1B2c3D4e5F6g7H8\"\n * ```\n */\nexport function generateSecureId(): string {\n  return `${Date.now()}_${generateRandomString(NUMERIX.SIXTEEN)}`;\n}\n\n/**\n * Sleep for specified milliseconds (async delay)\n * @param ms - Milliseconds to sleep\n * @returns Promise that resolves after the delay\n * @example\n * ```typescript\n * await sleep(1000); // Wait 1 second\n * ```\n */\nexport function sleep(ms: number): Promise<void> {\n  return new Promise(resolve => globalThis.setTimeout(resolve, ms));\n}\n\n/**\n * Mask sensitive data fields for safe logging\n * @param data - Object containing potentially sensitive data\n * @param sensitiveFields - Array of field names to mask (default: ['password', 'token', 'secret'])\n * @returns Object with sensitive fields masked\n * @example\n * ```typescript\n * const masked = maskSensitiveData({ email: 'user@example.com', password: 'secret123' });\n * // Result: { email: 'user@example.com', password: 'secr*****' }\n * ```\n */\nexport function maskSensitiveData(\n  data: unknown,\n  sensitiveFields: string[] = ['password', 'token', 'secret']\n): unknown {\n  if (typeof data !== 'object' || data === null) {\n    return data;\n  }\n\n  // Type assertion to allow indexing by string\n  const masked: Record<string, string> = { ...(data as Record<string, string>) };\n  const four  = 4;\n  for (const field of sensitiveFields) {\n    if (field in masked) {\n      const value = masked[field];\n      if (typeof value === 'string' && value.length > 0) {\n        masked[field] = value.substring(0, four) + '*'.repeat(Math.max(0, value.length - four));\n      }\n    }\n  }\n  \n  return masked;\n}\n\n"]}