@rineex/auth-core 0.0.2 → 0.0.4

package/src/domain/token/aggregates/token.aggregate.ts

@@ -0,0 +1,34 @@
+import { AggregateRoot, CreateEntityProps } from '@rineex/ddd';
+import { IdentityId } from '@/domain/identity';
+
+interface TokenProps extends CreateEntityProps<IdentityId> {
+  readonly identityId: IdentityId;
+  readonly expiresAt: Date;
+  revokedAt?: Date;
+}
+
+export class Token extends AggregateRoot<IdentityId> {
+  protected constructor(private props: TokenProps) {
+    super(props);
+  }
+
+  public revoke(at: Date): void {
+    if (this.props.revokedAt) return;
+
+    this.mutate(draft => {
+      draft.revokedAt = at;
+    });
+  }
+
+  public isActive(now = new Date()): boolean {
+    return (
+      !this.props.revokedAt && this.props.expiresAt.getTime() > now.getTime()
+    );
+  }
+
+  validate(): void {
+    if (this.props.expiresAt.getTime() <= Date.now()) {
+      throw new Error('Token already expired');
+    }
+  }
+}

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

@@ -0,0 +1,29 @@
+import { InvalidAuthTokenViolation } from '@/domain/violations/invalid-auth-token.violation';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+/**
+ * Represents a cryptographic authentication token.
+ *
+ * IMPORTANT:
+ * - This is NOT a JWT
+ * - This is NOT a bearer string
+ * - This is a domain-level proof of authentication
+ *
+ * Concrete formats live in adapters.
+ */
+export abstract class AuthToken extends PrimitiveValueObject<string> {
+  /**
+   * Token type identifier.
+   * Used for routing to correct adapters.
+   */
+  abstract readonly type: string;
+
+  protected validate(value: string): void {
+    if (value.length < 32) {
+      throw InvalidAuthTokenViolation.create({
+        actualLength: value.length,
+        minLength: 32,
+      });
+    }
+  }
+}

package/src/domain/token/value-objects/session-token.vo.ts

@@ -0,0 +1,14 @@
+import { AuthToken } from './auth-token.vo';
+
+/**
+ * Token bound to a session lifecycle.
+ */
+export class SessionToken extends AuthToken {
+  get type() {
+    return 'session';
+  }
+
+  public static create(value: string): SessionToken {
+    return new SessionToken(value);
+  }
+}

package/src/domain/violations/auth-domain.violation.ts

@@ -0,0 +1,9 @@
+import { DomainViolation } from '@rineex/ddd';
+
+/**
+ * Base class for all authentication domain violations.
+ *
+ * Auth domain MUST only throw DomainViolation objects.
+ * Mapping to native Error happens at application or adapter layer.
+ */
+export abstract class AuthDomainViolation extends DomainViolation {}

package/src/domain/violations/invalid-auth-token.violation.ts

@@ -0,0 +1,13 @@
+import { AuthDomainViolation } from './auth-domain.violation';
+
+/**
+ * Raised when an authentication token violates domain invariants.
+ */
+export class InvalidAuthTokenViolation extends AuthDomainViolation {
+  readonly code = 'AUTH_TOKEN_INVALID';
+  readonly message = 'Authentication token is invalid';
+
+  public static create(details: { actualLength: number; minLength: number }) {
+    return new InvalidAuthTokenViolation(details);
+  }
+}

package/src/domain/violations/invalid-scope.violation.ts

@@ -0,0 +1,10 @@
+import { DomainViolation } from '@rineex/ddd';
+
+export class InvalidScopeViolation extends DomainViolation {
+  public readonly code = 'auth.scope.invalid';
+  public readonly message = 'Scope format is invalid';
+
+  public static create(): InvalidScopeViolation {
+    return new InvalidScopeViolation();
+  }
+}

package/src/domain/violations/invalid-session.violation.ts

@@ -0,0 +1,13 @@
+import { AuthDomainViolation } from './auth-domain.violation';
+
+/**
+ * Raised when a session invariant is violated.
+ */
+export class InvalidSessionViolation extends AuthDomainViolation {
+  readonly code = 'session.invalid';
+  readonly message = 'Session state is invalid';
+
+  public static create(): InvalidSessionViolation {
+    return new InvalidSessionViolation();
+  }
+}

package/src/index.ts

@@ -1 +1,3 @@
-export {};
+export * from './domain';
+export * from './ports';
+export * from './types';

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

@@ -1,4 +1,4 @@
-import { AuthMethod } from '@/domain/value-objects/auth-method.vo';
+import { AuthMethod } from '@/domain/identity/value-objects';
 import { AuthContext } from '@/types/auth-context.type';
 
 /**

package/src/ports/inbound/index.ts

@@ -0,0 +1,2 @@
+export * from './auth-method.port';
+export * from './start-auth.command';

package/src/ports/inbound/start-auth.command.ts

@@ -0,0 +1,28 @@
+import { AuthMethodName } from '@/types/auth-method.type';
+import { AuthContext } from '@/types/auth-context.type';
+import { IdentityId } from '@/domain';
+
+/**
+ * Command representing a request to start authentication.
+ *
+ * This is a pure use-case input.
+ * It is NOT tied to HTTP, RPC, GraphQL, or CLI.
+ */
+export type StartAuthenticationCommand = {
+  /**
+   * Authentication method requested.
+   * Strongly typed and autocomplete-safe.
+   */
+  readonly method: AuthMethodName;
+
+  /**
+   * Optional identity hint.
+   * Used for passwordless, SSO, or known users.
+   */
+  readonly identityId?: IdentityId;
+
+  /**
+   * Execution context for auditing, correlation, and risk.
+   */
+  readonly context: AuthContext;
+};

package/src/ports/index.ts

@@ -0,0 +1,2 @@
+export * from './inbound';
+export * from './outbound';

package/src/ports/log/log.port.ts

@@ -0,0 +1,25 @@
+/**
+ * Application-level logger port.
+ *
+ * Must be:
+ * - side-effect only
+ * - non-throwing
+ * - fast
+ *
+ * Domain must never depend on this.
+ */
+export type LoggerPort = {
+  info: (message: string, metadata?: Readonly<Record<string, unknown>>) => void;
+
+  debug: (
+    message: string,
+    metadata?: Readonly<Record<string, unknown>>,
+  ) => void;
+
+  warn: (message: string, metadata?: Readonly<Record<string, unknown>>) => void;
+
+  error: (
+    message: string,
+    metadata?: Readonly<Record<string, unknown>>,
+  ) => void;
+};

package/src/ports/mfa/mfa-clock.port.ts

@@ -0,0 +1,11 @@
+/**
+ * Time abstraction for MFA logic.
+ *
+ * Required for:
+ * - expiration checks
+ * - deterministic testing
+ * - avoiding Date.now() in domain
+ */
+export type MfaClock = {
+  now: () => Date;
+};

package/src/ports/mfa/mfa-session-id-generator.port.ts

@@ -0,0 +1,15 @@
+import { MfaSessionId } from '@/domain/mfa/value-objects/mfa-session-id.vo';
+
+/**
+ * Generates MFA session identifiers.
+ *
+ * Examples:
+ * - ULID
+ * - UUIDv7
+ * - KSUID
+ *
+ * Domain does NOT care.
+ */
+export type MfaSessionIdGenerator = {
+  generate: () => MfaSessionId;
+};

package/src/ports/mfa/mfa-session-repository.port.ts

@@ -0,0 +1,31 @@
+import { MfaSessionId } from '@/domain/mfa/value-objects/mfa-session-id.vo';
+import { MFASession } from '@/domain/mfa/aggregates/mfa-session.aggregate';
+import { IdentityId } from '@/domain';
+
+/**
+ * Persistence port for MFA sessions.
+ *
+ * Implementations may use:
+ * - SQL
+ * - NoSQL
+ * - Redis
+ * - In-memory
+ *
+ * Domain MUST NOT know which.
+ */
+export type MfaSessionRepository = {
+  /**
+   * Find MFA session by aggregate id.
+   */
+  findById: (id: MfaSessionId) => Promise<MFASession | null>;
+
+  /**
+   * Find active MFA session for an identity.
+   */
+  findActiveByIdentity: (identityId: IdentityId) => Promise<MFASession | null>;
+
+  /**
+   * Persist MFA session state.
+   */
+  save: (session: MFASession) => Promise<void>;
+};

package/src/ports/observability/observability-event.port.ts

@@ -0,0 +1,16 @@
+import { ObservabilityEvent } from '@/types/observability-event';
+
+/**
+ * Observability event emitter.
+ *
+ * Used for:
+ * - audit logs
+ * - security monitoring
+ * - metrics
+ * - tracing
+ *
+ * Must be non-blocking and non-throwing.
+ */
+export type ObservabilityEventPort = {
+  emit: (event: ObservabilityEvent) => void;
+};

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

@@ -6,6 +6,6 @@ import { AuthenticationAttempt } from '@/domain/aggregates/authentication-attemp
  * Implementation is infrastructure-specific.
  */
 export type AuthenticationAttemptRepositoryPort = {
-  save: (attempt: AuthenticationAttemptRepositoryPort) => Promise<void>;
+  save: (attempt: AuthenticationAttempt) => Promise<void>;
   findById: (id: string) => Promise<AuthenticationAttempt | null>;
 };

package/src/ports/outbound/domain-event-publisher.port.ts

@@ -0,0 +1,13 @@
+import { DomainEvent } from '@rineex/ddd';
+
+/**
+ * Publishes domain events emitted by aggregates.
+ *
+ * Implementations may:
+ * - dispatch to message bus
+ * - log events
+ * - forward to observability stack
+ */
+export type DomainEventPublisherPort = {
+  publish: (events: readonly DomainEvent[]) => Promise<void>;
+};

package/src/ports/outbound/index.ts

@@ -0,0 +1,2 @@
+export * from './authentication-attempt.repository.port';
+export * from './domain-event-publisher.port';

package/src/ports/outbound/session.repository.port.ts

@@ -0,0 +1,9 @@
+import { SessionToken } from '@/domain/token/value-objects/session-token.vo';
+import { SessionId } from '@/domain/session/value-objects/session-id.vo';
+import { Session } from '@/domain/session/entities/session.entity';
+
+export type SessionRepositoryPort = {
+  save: (session: Session) => Promise<void>;
+  findById: (id: SessionId) => Promise<Session | null>;
+  findByToken: (token: SessionToken) => Promise<Session | null>;
+};

package/src/ports/repositories/oauth-authorization.repository.ts

@@ -0,0 +1,21 @@
+import { OauthAuthorization } from '@/domain/oauth/aggregates/oauth-authorization.aggregate';
+
+export type OAuthAuthorizationRepository = {
+  /**
+   * Persists an OAuth authorization aggregate.
+   */
+  save: (authorization: OauthAuthorization) => Promise<void>;
+
+  /**
+   * Loads authorization by its identifier.
+   */
+  getById: (id: string) => Promise<OauthAuthorization | null>;
+
+  /**
+   * Finds active authorization by client and identity.
+   */
+  findActiveByClientAndIdentity: (params: {
+    readonly clientId: string;
+    readonly identityId: string;
+  }) => Promise<OauthAuthorization | null>;
+};

package/src/ports/repositories/token.repository.ts

@@ -0,0 +1,11 @@
+export type TokenRepository = {
+  save: (token: Token) => Promise<void>;
+
+  getById: (id: string) => Promise<Token | null>;
+
+  /**
+   * Revokes all active tokens for an identity.
+   * Used for logout-all / security events.
+   */
+  revokeAllByIdentity: (identityId: string) => Promise<void>;
+};

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

@@ -0,0 +1,10 @@
+/**
+ * Registry of authentication factor identifiers.
+ *
+ * Used for MFA and step-up authentication.
+ */
+export type AuthFactorRegistry = {
+  password: 'password';
+};
+
+export type AuthFactorName = keyof AuthFactorRegistry;

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

@@ -0,0 +1,20 @@
+/**
+ * Registry for authentication method identifiers.
+ *
+ * This type is intentionally open for module augmentation.
+ * Each auth-method package extends this registry.
+ */
+export type AuthMethodRegistry = {
+  readonly passwordless: true;
+  readonly otp: true;
+};
+
+/**
+ * Union of all registered authentication method names.
+ *
+ * This enables:
+ * - IDE autocomplete
+ * - Type safety
+ * - Plugin-based extension
+ */
+export type AuthMethodName = keyof AuthMethodRegistry;

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

@@ -0,0 +1,16 @@
+/**
+ * Registry of authentication policy identifiers.
+ *
+ * This registry is intentionally open for module augmentation.
+ * Each policy package extends this type.
+ */
+export type AuthPolicyRegistry = {
+  readonly base: true;
+};
+
+/**
+ * Union of all registered authentication policy names.
+ *
+ * Enables autocomplete and compile-time safety.
+ */
+export type AuthPolicyName = keyof AuthPolicyRegistry;

package/src/types/identity-provider.type.ts

@@ -0,0 +1,8 @@
+/**
+ * Registry of identity provider identifiers.
+ *
+ * Supports social login, enterprise SSO, and internal IdPs.
+ */
+export type IdentityProviderRegistry = {};
+
+export type IdentityProviderName = keyof IdentityProviderRegistry;

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from './auth-context.type';
+export * from './auth-factor.type';
+export * from './auth-method.type';
+export * from './auth-policy.type';
+export * from './identity-provider.type';
+export * from './risk-signal.type';

package/src/types/observability-event.ts

@@ -0,0 +1,33 @@
+/**
+ * Base structure for observability events.
+ *
+ * These events:
+ * - are NOT domain events
+ * - must be safe to store long-term
+ * - must never contain secrets
+ */
+export type ObservabilityEventProps = {
+  readonly name: string;
+  readonly occurredAt?: Date;
+  readonly payload: Readonly<Record<string, unknown>>;
+};
+
+export class ObservabilityEvent {
+  public readonly name: string;
+  public readonly occurredAt: Date;
+  public readonly payload: Readonly<Record<string, unknown>>;
+
+  constructor(props: ObservabilityEventProps) {
+    this.name = props.name;
+    this.occurredAt = props.occurredAt ?? new Date();
+    this.payload = props.payload;
+  }
+
+  toPrimitives() {
+    return {
+      occurredAt: this.occurredAt.toISOString(),
+      payload: this.payload,
+      name: this.name,
+    };
+  }
+}

package/src/types/risk-signal.type.ts

@@ -0,0 +1,11 @@
+/**
+ * Registry of risk signal identifiers.
+ *
+ * Signals are produced by detectors and consumed by policies.
+ */
+export type RiskSignalRegistry = {};
+
+/**
+ * Union of all registered risk signal names.
+ */
+export type RiskSignalName = keyof RiskSignalRegistry;

package/src/utils/default-if-blank.util.ts

@@ -0,0 +1,46 @@
+import isEmpty from 'lodash.isempty';
+import isNil from 'lodash.isnil';
+
+/**
+ * Returns a default value if the input string is nil or empty.
+ *
+ * @param value - The input string to check.
+ * @param defaultValue - The default string to return if input is nil or empty.
+ * @returns The input string if non-empty, otherwise the default value.
+ */
+export function defaultIfBlank<T extends string = string>(
+  value: T,
+  defaultValue: T,
+): T {
+  if (isNil(value) || isEmpty(value)) {
+    return defaultValue;
+  }
+
+  return value;
+}
+
+/**
+ * Returns null if the input string is nil or empty, otherwise returns the input.
+ *
+ * @param value - The input string to check.
+ * @returns The input string if non-empty, otherwise null.
+ */
+export function defaultIfNilOrEmpty<T extends string = string>(
+  value: T | null | undefined,
+): T | null {
+  if (isNil(value) || isEmpty(value)) {
+    return null;
+  }
+
+  return value;
+}
+
+export function defaultIfUndefinedOrEmpty<T extends string = string>(
+  value: T | undefined,
+): T | undefined {
+  if (isNil(value) || isEmpty(value)) {
+    return undefined;
+  }
+
+  return value;
+}

package/tsconfig.json

@@ -2,18 +2,21 @@
   "compilerOptions": {
     "module": "commonjs",
     "declaration": true,
-    "noImplicitAny": false,
     "noUnusedLocals": false,
+    "strictNullChecks": true,
     "importHelpers": true,
     "removeComments": false,
     "noLib": false,
     "emitDecoratorMetadata": true,
     "esModuleInterop": true,
     "experimentalDecorators": true,
+    "noImplicitThis": true,
     "target": "es6",
     "sourceMap": false,
     "outDir": "./dist",
+    "noImplicitAny": true,
     "rootDir": ".",
+    "strictPropertyInitialization": true,
     "paths": {
       "@/*": ["./src/*"]
     },

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

@@ -1,13 +0,0 @@
-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/value-objects/auth-method.vo.ts

@@ -1,21 +0,0 @@
-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');
-    }
-  }
-}