@rineex/auth-core 0.0.1 → 0.0.2

package/eslint.config.mjs

@@ -0,0 +1,58 @@
+import config from '@rineex/eslint-config/base';
+import db from '@rineex/eslint-config/db';
+
+export default [
+  ...config,
+  ...db,
+
+  {
+    rules: {
+      '@typescript-eslint/consistent-type-definitions': ['off'],
+      '@typescript-eslint/consistent-type-imports': 'off',
+      '@typescript-eslint/no-extraneous-class': 'off',
+      'max-params': ['error', 5],
+    },
+  },
+  {
+    rules: {
+      'perfectionist/sort-imports': [
+        'error',
+        {
+          groups: [
+            'builtin', // Node.js built-in modules (e.g., 'fs', 'path')
+            'external', // External dependencies (e.g., 'react', 'lodash')
+            'nestjs',
+            'common', // Your custom group for '@/common/*'
+            'internal', // Other internal imports (e.g., '~/components/Button')
+            'parent', // Parent directory imports (e.g., '../utils')
+            'sibling', // Same directory imports (e.g., './config')
+            'index', // Index file imports (e.g., './')
+          ],
+          customGroups: {
+            value: {
+              nestjs: '@nestjs/*',
+              common: '@/*', // Matches imports like '@/common/utils', '@/common/helpers', etc.
+            },
+          },
+
+          newlinesBetween: 'always',
+          type: 'line-length',
+
+          order: 'desc',
+        },
+      ],
+      'perfectionist/sort-objects': [
+        'error',
+        {
+          type: 'line-length',
+          order: 'desc',
+        },
+      ],
+
+      'perfectionist/sort-decorators': [
+        'error',
+        { type: 'line-length', order: 'desc' },
+      ],
+    },
+  },
+];

package/package.json

@@ -1,49 +1,50 @@
 {
   "name": "@rineex/auth-core",
-  "version": "0.0.1",
-  "description": "Auth Core package for Rineex core modules",
+  "version": "0.0.2",
+  "description": "Authentication Core package for Rineex core modules",
   "author": "Rineex Team",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist/**"
-  ],
-  "sideEffects": false,
-  "devDependencies": {
-    "@changesets/cli": "2.29.8",
-    "@types/node": "24.10.4",
-    "@vitest/ui": "4.0.16",
-    "tslib": "2.8.1",
-    "tsup": "8.5.1",
-    "typescript": "5.9.3",
-    "vite-tsconfig-paths": "6.0.2",
-    "vitest": "4.0.16",
-    "@rineex/eslint-config": "0.0.0",
-    "@rineex/typescript-config": "0.0.0"
-  },
   "keywords": [
     "rineex",
-    "auth",
     "authentication",
+    "auth",
     "social-login",
     "otp",
     "passwordless",
     "sso"
   ],
-  "license": "Apache-2.0",
   "publishConfig": {
     "provenance": true,
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "devDependencies": {
+    "@changesets/cli": "2.29.8",
+    "@types/node": "24.10.4",
+    "@vitest/ui": "4.0.16",
+    "tslib": "2.8.1",
+    "tsup": "8.5.1",
+    "type-fest": "5.3.1",
+    "typescript": "5.9.3",
+    "vite-tsconfig-paths": "6.0.2",
+    "vitest": "4.0.16",
+    "@rineex/eslint-config": "0.0.0",
+    "@rineex/typescript-config": "0.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/rineex/core.git",
-    "directory": "packages/auth-core"
+    "directory": "packages/authentication/core"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@rineex/ddd": "1.5.1"
   },
   "scripts": {
     "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --watch --passWithNoTests",
     "lint": "eslint 'src/**/*.ts'",
     "check-types": "tsc --noEmit",
     "build": "tsup"

package/src/domain/aggregates/authentication-attempt.aggregate.ts

@@ -0,0 +1,119 @@
+import { AggregateRoot } from '@rineex/ddd';
+
+import { AuthenticationSucceededEvent } from '../events/authentication-succeeded.event';
+import { AuthenticationStartedEvent } from '../events/authentication-started.event';
+import { AuthenticationFailedEvent } from '../events/authentication-failed.event';
+import { AuthAttemptId } from '../value-objects/auth-attempt-id.vo';
+import { AuthStatus } from '../value-objects/auth-status.vo';
+import { AuthMethod } from '../value-objects/auth-method.vo';
+import { IdentityId } from '../value-objects/identity-id.vo';
+
+type Props = {
+  status: AuthStatus;
+  method: AuthMethod;
+  identityId?: IdentityId;
+};
+
+/**
+ * Aggregate Root representing a single authentication attempt.
+ *
+ * Responsibilities:
+ * - Enforce authentication lifecycle invariants
+ * - Emit auditable domain events
+ * - Prevent invalid state transitions
+ *
+ * This aggregate DOES NOT:
+ * - Perform authentication
+ * - Talk to infrastructure
+ * - Know about HTTP or sessions
+ */
+export class AuthenticationAttempt extends AggregateRoot<Props> {
+  private constructor(id: AuthAttemptId, props: Props) {
+    super({
+      createdAt: new Date(),
+      props,
+      id,
+    });
+  }
+
+  // This "casts" the ID for this specific class only
+  public override get id(): AuthAttemptId {
+    return super.id as AuthAttemptId;
+  }
+
+  /**
+   * Factory method to start a new authentication attempt.
+   */
+  static start(
+    id: AuthAttemptId,
+    method: AuthMethod,
+    identityId?: IdentityId,
+  ): AuthenticationAttempt {
+    const attempt = new AuthenticationAttempt(id, {
+      status: AuthStatus.create('PENDING'),
+      identityId,
+      method,
+    });
+
+    attempt.addEvent(new AuthenticationStartedEvent(id, method));
+
+    return attempt;
+  }
+
+  /**
+   * Marks the authentication attempt as successful.
+   *
+   * @throws Error if already completed
+   */
+  succeed(): void {
+    if (this.props.status.isNot('PENDING')) {
+      throw new Error('Authentication attempt already completed');
+    }
+
+    this.updateProps(props => ({
+      ...props,
+      status: AuthStatus.create('SUCCEEDED'),
+    }));
+
+    const ev = new AuthenticationSucceededEvent(this.id);
+
+    this.addEvent(ev);
+  }
+
+  /**
+   * Marks the authentication attempt as failed.
+   *
+   * @throws Error if already completed
+   */
+  fail(reason: string): void {
+    if (this.props.status.isNot('PENDING')) {
+      throw new Error('Authentication attempt already completed');
+    }
+
+    if (!reason || reason.length < 3) {
+      throw new Error('Failure reason must be provided');
+    }
+
+    this.updateProps(props => ({
+      ...props,
+      status: AuthStatus.create('FAILED'),
+    }));
+
+    this.addEvent(new AuthenticationFailedEvent(this.id));
+  }
+
+  /**
+   * Aggregate invariant validation.
+   *
+   * Called automatically before domain events are added.
+   */
+  validate(): void {
+    if (!this.props.method) {
+      throw new Error('AuthenticationAttempt must have a method');
+    }
+
+    if (!this.props.status) {
+      throw new Error('AuthenticationAttempt must have a status');
+    }
+  }
+}

package/src/domain/entities/identity.entity.ts

@@ -0,0 +1,13 @@
+import { Entity } from '@rineex/ddd';
+
+import { IdentityId } from '../value-objects/identity-id.vo';
+
+/**
+ * Represents an authenticated or authenticating identity.
+ *
+ * This entity is intentionally minimal.
+ * All profile, permissions, and roles belong elsewhere.
+ */
+export class Identity extends Entity<IdentityId> {
+  validate(): void {}
+}

package/src/domain/events/authentication-failed.event.ts

@@ -0,0 +1,24 @@
+import { DomainEvent } from '@rineex/ddd';
+
+import { AuthAttemptId } from '../value-objects/auth-attempt-id.vo';
+
+/**
+ * Emitted when an authentication attempt failed.
+ */
+export class AuthenticationFailedEvent extends DomainEvent {
+  public get eventName(): string {
+    return 'authentication.auth_attempt.failed';
+  }
+
+  constructor(public readonly attemptId: AuthAttemptId) {
+    super({
+      payload: {
+        attemptId: attemptId.toString(),
+      },
+      aggregateId: attemptId.toString(),
+      id: crypto.randomUUID(),
+      occurredAt: Date.now(),
+      schemaVersion: 1,
+    });
+  }
+}

package/src/domain/events/authentication-started.event.ts

@@ -0,0 +1,29 @@
+import { DomainEvent } from '@rineex/ddd';
+
+import { AuthAttemptId } from '../value-objects/auth-attempt-id.vo';
+import { AuthMethod } from '../value-objects/auth-method.vo';
+
+/**
+ * Emitted when an authentication attempt begins.
+ */
+export class AuthenticationStartedEvent extends DomainEvent {
+  public get eventName(): string {
+    return 'authentication.authentication_started';
+  }
+
+  constructor(
+    public readonly attemptId: AuthAttemptId,
+    public readonly method: AuthMethod,
+  ) {
+    super({
+      payload: {
+        attemptId: attemptId.toString(),
+        method: method.toString(),
+      },
+      aggregateId: attemptId.toString(),
+      id: crypto.randomUUID(),
+      occurredAt: Date.now(),
+      schemaVersion: 1,
+    });
+  }
+}

package/src/domain/events/authentication-succeeded.event.ts

@@ -0,0 +1,24 @@
+import { DomainEvent } from '@rineex/ddd';
+
+import { AuthAttemptId } from '../value-objects/auth-attempt-id.vo';
+
+/**
+ * Emitted when an authentication attempt succeeds.
+ */
+export class AuthenticationSucceededEvent extends DomainEvent {
+  public get eventName(): string {
+    return 'authentication.auth_attempt.succeeded';
+  }
+
+  constructor(public readonly attemptId: AuthAttemptId) {
+    super({
+      payload: {
+        attemptId: attemptId.toString(),
+      },
+      aggregateId: attemptId.toString(),
+      id: crypto.randomUUID(),
+      occurredAt: Date.now(),
+      schemaVersion: 1,
+    });
+  }
+}

package/src/domain/value-objects/auth-attempt-id.vo.ts

@@ -0,0 +1,19 @@
+import { UUID } from '@rineex/ddd';
+
+/**
+ * Represents a globally unique identifier for an authentication attempt.
+ *
+ * This ID is used for:
+ * - Correlation across logs
+ * - Event causation
+ * - Security auditing
+ *
+ * Must be generated externally (UUIDv7 recommended).
+ */
+export class AuthAttemptId extends UUID {
+  protected validate(value: string): void {
+    if (!value || value.length < 16) {
+      throw new Error('AuthAttemptId must be a valid non-empty identifier');
+    }
+  }
+}

package/src/domain/value-objects/auth-method.vo.ts

@@ -0,0 +1,21 @@
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+/**
+ * Represents the authentication method requested or used.
+ *
+ * Examples:
+ * - passwordless
+ * - otp
+ * - oauth
+ * - oidc
+ * - passkey
+ *
+ * This is a value object, NOT a strategy.
+ */
+export class AuthMethod extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!value) {
+      throw new Error('AuthMethod cannot be empty');
+    }
+  }
+}

package/src/domain/value-objects/auth-status.vo.ts

@@ -0,0 +1,38 @@
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+type AuthStatusType = 'FAILED' | 'PENDING' | 'SUCCEEDED';
+
+/**
+ * Represents the lifecycle state of an authentication attempt.
+ *
+ * This is intentionally restrictive to avoid invalid transitions.
+ */
+export class AuthStatus extends PrimitiveValueObject<AuthStatusType> {
+  protected validate(value: AuthStatusType): void {
+    if (!['FAILED', 'PENDING', 'SUCCEEDED'].includes(value)) {
+      throw new Error(`Invalid AuthStatus: ${value}`);
+    }
+  }
+
+  /**
+   * Checks if the current auth status matches the provided value.
+   * @param value - The auth status type to compare against
+   * @returns True if the current status matches the provided value, false otherwise
+   */
+  public is(value: AuthStatusType): boolean {
+    return this.value === value;
+  }
+
+  /**
+   * Checks if the current authentication status is not equal to the provided value.
+   * @param value - The authentication status type to compare against
+   * @returns True if the current status differs from the provided value, false otherwise
+   */
+  public isNot(value: AuthStatusType): boolean {
+    return this.value !== value;
+  }
+
+  static create(value: AuthStatusType): AuthStatus {
+    return new AuthStatus(value);
+  }
+}

package/src/domain/value-objects/identity-id.vo.ts

@@ -0,0 +1,22 @@
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+/**
+ * Represents the canonical identity identifier in the auth domain.
+ *
+ * This does NOT imply:
+ * - user
+ * - account
+ * - profile
+ *
+ * It is intentionally abstract to support:
+ * - enterprise SSO
+ * - external IdPs
+ * - service identities
+ */
+export class IdentityId extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!value || value.length < 8) {
+      throw new Error('IdentityId must be a valid identifier');
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export {};

package/src/ports/inbound/auth-method.port.ts

@@ -0,0 +1,18 @@
+import { AuthMethod } from '@/domain/value-objects/auth-method.vo';
+import { AuthContext } from '@/types/auth-context.type';
+
+/**
+ * Contract implemented by authentication method modules.
+ *
+ * Examples:
+ * - OTP
+ * - OAuth
+ * - Passkeys
+ *
+ * Auth-core depends on this abstraction, not implementations.
+ */
+export type AuthMethodPort = {
+  readonly method: AuthMethod;
+
+  authenticate: (context: AuthContext) => Promise<void>;
+};

package/src/ports/outbound/authentication-attempt.repository.port.ts

@@ -0,0 +1,11 @@
+import { AuthenticationAttempt } from '@/domain/aggregates/authentication-attempt.aggregate';
+
+/**
+ * Persistence port for authentication attempts.
+ *
+ * Implementation is infrastructure-specific.
+ */
+export type AuthenticationAttemptRepositoryPort = {
+  save: (attempt: AuthenticationAttemptRepositoryPort) => Promise<void>;
+  findById: (id: string) => Promise<AuthenticationAttempt | null>;
+};

package/src/types/auth-context.type.ts

@@ -0,0 +1,11 @@
+/**
+ * Context passed across authentication boundaries.
+ *
+ * This type is intentionally open-ended and extensible.
+ */
+export type AuthContext = {
+  readonly correlationId: string;
+  readonly ipAddress?: string;
+  readonly userAgent?: string;
+  readonly metadata?: Record<string, unknown>;
+};

package/tsconfig.build.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.json",
+
+  "include": ["src/**/*", "tsup.config.ts", "vitest.config.ts"],
+  "exclude": ["node_modules", "dist", "test", "**/*.{spec,test}.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": true,
+    "noImplicitAny": false,
+    "noUnusedLocals": false,
+    "importHelpers": true,
+    "removeComments": false,
+    "noLib": false,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "target": "es6",
+    "sourceMap": false,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "lib": ["es7", "ES2021.WeakRef", "ES2022"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*", "tsup.config.ts", "vitest.config.ts"],
+  "exclude": ["node_modules"]
+}

package/tsup.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig(() => ({
+  // eslint-disable-next-line n/no-process-env
+  minify: process.env.CI === 'true',
+  tsconfig: 'tsconfig.build.json',
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  dts: true,
+}));

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['./src/**/*.spec.ts'],
+    globals: true,
+    root: './',
+  },
+
+  plugins: [tsconfigPaths()],
+});

package/dist/index.d.mts

@@ -1,2 +0,0 @@
-
-export {  }

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-
-export {  }

package/dist/index.js

@@ -1,2 +0,0 @@
-var t=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var d=(o,e,x,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let p of b(e))!c.call(o,p)&&p!==x&&t(o,p,{get:()=>e[p],enumerable:!(r=a(e,p))||r.enumerable});return o};var f=o=>d(t({},"__esModule",{value:!0}),o);var g={};module.exports=f(g);
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Auth Core Package for Rineex\n * Provides core authentication and authorization functionality\n */\n\nexport {};\n"],"mappings":"kWAAA,IAAAA,EAAA,kBAAAC,EAAAD","names":["index_exports","__toCommonJS"]}

package/dist/index.mjs

@@ -1 +0,0 @@
-//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}