@rineex/auth-core 0.0.2 → 0.0.4

package/src/domain/oauth/aggregates/oauth-authorization.aggregate.ts

@@ -0,0 +1,106 @@
+import isNil from 'lodash.isnil';
+
+import { defaultIfNilOrEmpty } from '@/utils/default-if-blank.util';
+import { AggregateRoot, CreateEntityProps } from '@rineex/ddd';
+import { IdentityId } from '@/domain/identity';
+
+import { AuthorizationAlreadyUsedViolation } from '../violations/authorization-already-used.violation';
+import { AuthorizationExpiredViolation } from '../violations/authorization-expired.violation';
+import { ConsentRequiredViolation } from '../violations/consent-required.violation';
+import { OAuthAuthorizationId } from '../value-objects/oauth-authorization-id.vo';
+import { AuthorizationCode } from '../value-objects/authorization-code.vo';
+import { CodeChallenge } from '../value-objects/code-challenge.vo';
+import { RedirectUri } from '../value-objects/redirect-uri.vo';
+import { ClientId } from '../value-objects/client-id.vo';
+import { ScopeSet } from '../value-objects/scope-set.vo';
+
+export interface OAuthAuthorizationProps extends CreateEntityProps<OAuthAuthorizationId> {
+  readonly identityId: IdentityId;
+  readonly clientId: ClientId;
+  readonly redirectUri: RedirectUri;
+  readonly scopes: ScopeSet;
+  readonly codeChallenge?: CodeChallenge;
+
+  consentGrantedAt?: Date;
+  authorizationCode?: AuthorizationCode;
+  readonly expiresAt: Date;
+}
+
+export class OauthAuthorization extends AggregateRoot<OAuthAuthorizationId> {
+  protected constructor(private props: OAuthAuthorizationProps) {
+    super(props);
+  }
+
+  validate() {
+    if (this.props.expiresAt.getTime() <= Date.now()) {
+      throw AuthorizationExpiredViolation.create();
+    }
+  }
+
+  issueAuthorizationCode(code: AuthorizationCode): void {
+    if (this.props.authorizationCode) {
+      throw AuthorizationAlreadyUsedViolation.create();
+    }
+
+    if (this.requiresConsent()) {
+      throw ConsentRequiredViolation.create();
+    }
+
+    this.props.authorizationCode = code;
+  }
+
+  isExpired(now: Date): boolean {
+    return now > this.props.expiresAt;
+  }
+
+  grantConsent(now: Date): void {
+    if (!this.requiresConsent()) {
+      return;
+    }
+
+    this.mutate(draft => {
+      draft.props.consentGrantedAt = now;
+    });
+
+    this.props.consentGrantedAt = now;
+  }
+
+  protected snapshot(): Record<string, unknown> {
+    return {
+      consentGrantedAt: this.props.consentGrantedAt?.toISOString() ?? null,
+      authorizationCode: this.props.authorizationCode?.toString() ?? null,
+    };
+  }
+
+  protected restore(snapshot: Record<string, unknown>): void {
+    this.props.consentGrantedAt = snapshot.consentGrantedAt
+      ? new Date(snapshot.consentGrantedAt as string)
+      : undefined;
+
+    this.props.authorizationCode = snapshot.authorizationCode
+      ? AuthorizationCode.create(snapshot.authorizationCode as string)
+      : undefined; // Assume fromString exists
+  }
+
+  requiresConsent(): boolean {
+    return isNil(this.props.consentGrantedAt);
+  }
+
+  toObject() {
+    return {
+      consentGrantedAt: defaultIfNilOrEmpty(
+        this.props.consentGrantedAt?.toISOString(),
+      ),
+      authorizationCode: defaultIfNilOrEmpty(
+        this.props.authorizationCode?.toString(),
+      ),
+      codeChallenge: defaultIfNilOrEmpty(this.props.codeChallenge?.toString()),
+      redirectUri: this.props.redirectUri.toString(),
+      expiresAt: this.props.expiresAt.toISOString(),
+      identityId: this.props.identityId.toString(),
+      scopes: this.props.scopes.toStringArray(),
+      clientId: this.props.clientId.toString(),
+      id: this.id.toString(),
+    };
+  }
+}

package/src/domain/oauth/entities/oauth-authorization.entity.ts

@@ -0,0 +1,50 @@
+import { CreateEntityProps, Entity } from '@rineex/ddd';
+
+import { InvalidRedirectUriViolation } from '../violations/invalid-redirect-uri.violation';
+import { OAuthAuthorizationId } from '../value-objects/oauth-authorization-id.vo';
+import { OAuthProvider } from '../value-objects/oauth-provider.vo';
+import { Pkce } from '../value-objects/pkce.vo';
+
+export interface OAuthAuthorizationProps extends CreateEntityProps<OAuthAuthorizationId> {
+  provider: OAuthProvider;
+  redirectUri: string;
+  scope: readonly string[];
+  pkce?: Pkce;
+}
+
+export class OAuthAuthorization extends Entity<OAuthAuthorizationId> {
+  constructor(public props: OAuthAuthorizationProps) {
+    super(props);
+  }
+
+  toObject(): Record<string, unknown> {
+    return {
+      pkce: this.props.pkce ? this.props.pkce.toJSON() : undefined,
+      redirectUri: this.props.redirectUri,
+      provider: this.props.provider,
+      scope: this.props.scope,
+      id: this.id.getValue(),
+    };
+  }
+
+  protected snapshot(): Record<string, unknown> {
+    return this.toObject();
+  }
+
+  protected restore(snapshot: Record<string, unknown>): void {
+    this.props.pkce = snapshot.pkce
+      ? Pkce.fromJSON(snapshot.pkce as Record<string, unknown>)
+      : undefined;
+    this.props.redirectUri = snapshot.redirectUri as string;
+    this.props.provider = snapshot.provider as OAuthProvider;
+    this.props.scope = snapshot.scope as string[];
+  }
+
+  validate(): void {
+    if (!this.props.redirectUri.startsWith('https://')) {
+      throw InvalidRedirectUriViolation.create({
+        redirectUri: this.props.redirectUri,
+      });
+    }
+  }
+}

package/src/domain/oauth/value-objects/authorization-code-id.vo.ts

@@ -0,0 +1,9 @@
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+export class AuthorizationCodeId extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!value || value.length < 32) {
+      throw new Error('Invalid authorization code');
+    }
+  }
+}

package/src/domain/oauth/value-objects/authorization-code.vo.ts

@@ -0,0 +1,18 @@
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+import { InvalidAuthorizationCodeViolation } from '../violations/invalid-authorization-code.violation';
+
+export class AuthorizationCode extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (value.length < 8) {
+      throw InvalidAuthorizationCodeViolation.create({
+        actualLength: value.length,
+        minLength: 8,
+      });
+    }
+  }
+
+  public static create(value: string): AuthorizationCode {
+    return new AuthorizationCode(value);
+  }
+}

package/src/domain/oauth/value-objects/client-id.vo.ts

@@ -0,0 +1,9 @@
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+export class ClientId extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!value || value.length < 8) {
+      throw new Error('Invalid client identifier');
+    }
+  }
+}

package/src/domain/oauth/value-objects/code-challenge-method.vo.ts

@@ -0,0 +1,15 @@
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+export type CodeChallengeMethodValue = 'plain' | 'S256';
+
+export class CodeChallengeMethod extends PrimitiveValueObject<CodeChallengeMethodValue> {
+  protected validate(value: CodeChallengeMethodValue): void {
+    if (value !== 'plain' && value !== 'S256') {
+      throw new Error('Unsupported code challenge method');
+    }
+  }
+
+  static create(value: CodeChallengeMethodValue): CodeChallengeMethod {
+    return new CodeChallengeMethod(value);
+  }
+}

package/src/domain/oauth/value-objects/code-challenge.vo.ts

@@ -0,0 +1,24 @@
+import { ValueObject } from '@rineex/ddd';
+
+import { CodeChallengeMethod } from './code-challenge-method.vo';
+
+export type CodeChallengeProps = {
+  readonly value: string;
+  readonly method: CodeChallengeMethod;
+};
+
+export class CodeChallenge extends ValueObject<CodeChallengeProps> {
+  protected validate(props: CodeChallengeProps): void {
+    if (!props.value || props.value.length < 32) {
+      throw new Error('Invalid code challenge value');
+    }
+  }
+
+  get method(): CodeChallengeMethod {
+    return this.props.method;
+  }
+
+  static create(value: string, method: CodeChallengeMethod): CodeChallenge {
+    return new CodeChallenge({ method, value });
+  }
+}

package/src/domain/oauth/value-objects/oauth-authorization-id.vo.ts

@@ -0,0 +1,19 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+class InvalidOAuthAuthorizationIdViolation extends AuthDomainViolation {
+  readonly code = 'OAUTH_AUTHORIZATION_ID_INVALID';
+  readonly message = 'OAuthAuthorization ID is invalid';
+
+  public static create(props: { value: string }) {
+    return new InvalidOAuthAuthorizationIdViolation(props);
+  }
+}
+
+export class OAuthAuthorizationId extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!value || value.length < 16) {
+      throw InvalidOAuthAuthorizationIdViolation.create({ value });
+    }
+  }
+}

package/src/domain/oauth/value-objects/oauth-provider.vo.ts

@@ -0,0 +1,15 @@
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+import { InvalidOAuthProviderViolation } from '../violations/invalid-oauth-provider.violation';
+
+export class OAuthProvider extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!value || value.length < 2) {
+      throw InvalidOAuthProviderViolation.create({ value });
+    }
+  }
+
+  public static create(value: string): OAuthProvider {
+    return new OAuthProvider(value);
+  }
+}

package/src/domain/oauth/value-objects/pkce.vo.ts

@@ -0,0 +1,29 @@
+import { ValueObject } from '@rineex/ddd';
+
+import { InvalidPkceViolation } from '../violations/invalid-pkce.violation';
+
+export type PkceProps = {
+  readonly codeVerifier: string;
+  readonly codeChallenge: string;
+  readonly method: 'plain' | 'S256';
+};
+
+export class Pkce extends ValueObject<PkceProps> {
+  protected validate(props: PkceProps): void {
+    if (!props.codeVerifier || !props.codeChallenge) {
+      throw InvalidPkceViolation.create(props);
+    }
+  }
+
+  public static create(props: PkceProps): Pkce {
+    return new Pkce(props);
+  }
+
+  public static fromJSON(json: Record<string, unknown>): Pkce {
+    return new Pkce({
+      codeChallenge: json.codeChallenge as string,
+      codeVerifier: json.codeVerifier as string,
+      method: json.method as 'plain' | 'S256',
+    });
+  }
+}

package/src/domain/oauth/value-objects/redirect-uri.vo.ts

@@ -0,0 +1,19 @@
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+import { InvalidRedirectUriViolation } from '../violations/invalid-redirect-uri.violation';
+
+export class RedirectUri extends PrimitiveValueObject<string> {
+  protected validate(url: string): void {
+    let parsed: URL;
+
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw InvalidRedirectUriViolation.create({ redirectUri: url });
+    }
+
+    if (parsed.protocol !== 'https:' || parsed.hash) {
+      throw InvalidRedirectUriViolation.create({ redirectUri: url });
+    }
+  }
+}

package/src/domain/oauth/value-objects/scope-set.vo.ts

@@ -0,0 +1,37 @@
+import { PrimitiveValueObject, ValueObject } from '@rineex/ddd';
+
+export class Scope extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!/^[-0-:_a-z]+$/.test(value)) {
+      throw new Error('Invalid scope format');
+    }
+  }
+
+  static create(scope: string): Scope {
+    return new Scope(scope);
+  }
+}
+
+export class ScopeSet extends ValueObject<ReadonlySet<Scope>> {
+  public static create() {
+    return new ScopeSet(new Set<Scope>());
+  }
+
+  protected validate(value: ReadonlySet<Scope>): void {
+    if (value.size === 0) {
+      throw new Error('At least one scope is required');
+    }
+  }
+
+  static fromStrings(scopes: readonly string[]): ScopeSet {
+    return new ScopeSet(new Set(scopes.map(scope => Scope.create(scope))));
+  }
+
+  has(scope: Scope): boolean {
+    return [...this.props].some(s => s.equals(scope));
+  }
+
+  toStringArray(): string[] {
+    return [...this.props].map(s => s.getValue());
+  }
+}

package/src/domain/oauth/violations/authorization-already-used.violation.ts

@@ -0,0 +1,10 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+
+export class AuthorizationAlreadyUsedViolation extends AuthDomainViolation {
+  readonly code = 'oauth.authorization.already_used';
+  readonly message = 'The OAuth authorization has already been used';
+
+  public static create(): AuthorizationAlreadyUsedViolation {
+    return new AuthorizationAlreadyUsedViolation();
+  }
+}

package/src/domain/oauth/violations/authorization-expired.violation.ts

@@ -0,0 +1,10 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+
+export class AuthorizationExpiredViolation extends AuthDomainViolation {
+  readonly code = 'oauth.authorization.expired';
+  readonly message = 'The OAuth authorization has expired';
+
+  public static create(): AuthorizationExpiredViolation {
+    return new AuthorizationExpiredViolation();
+  }
+}

package/src/domain/oauth/violations/consent-required.violation.ts

@@ -0,0 +1,10 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+
+export class ConsentRequiredViolation extends AuthDomainViolation {
+  readonly code = 'oauth.consent.required';
+  readonly message = 'User consent is required for this OAuth authorization';
+
+  public static create(): ConsentRequiredViolation {
+    return new ConsentRequiredViolation();
+  }
+}

package/src/domain/oauth/violations/invalid-authorization-code.violation.ts

@@ -0,0 +1,12 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+
+export class InvalidAuthorizationCodeViolation extends AuthDomainViolation {
+  readonly code = 'AUTH_CODE_INVALID';
+  readonly message = 'Authorization code is invalid';
+
+  public static create(
+    details?: Record<string, unknown>,
+  ): InvalidAuthorizationCodeViolation {
+    return new InvalidAuthorizationCodeViolation({ details });
+  }
+}

package/src/domain/oauth/violations/invalid-oauth-provider.violation.ts

@@ -0,0 +1,13 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+
+export class InvalidOAuthProviderViolation extends AuthDomainViolation {
+  readonly code = 'OAUTH_PROVIDER_INVALID';
+  readonly message = 'OAuth provider identifier is invalid';
+
+  public static create(props: { value: string }) {
+    return new InvalidOAuthProviderViolation({
+      ...props,
+      message: `OAuth provider identifier "${props.value}" is invalid`,
+    });
+  }
+}

package/src/domain/oauth/violations/invalid-pkce.violation.ts

@@ -0,0 +1,12 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+
+export class InvalidPkceViolation extends AuthDomainViolation {
+  readonly code = 'PKCE_INVALID';
+  readonly message = 'PKCE parameters are invalid';
+
+  public static create(
+    details?: Record<string, unknown>,
+  ): InvalidPkceViolation {
+    return new InvalidPkceViolation({ details });
+  }
+}

package/src/domain/oauth/violations/invalid-redirect-uri.violation.ts

@@ -0,0 +1,10 @@
+import { AuthDomainViolation } from '@/domain/violations/auth-domain.violation';
+
+export class InvalidRedirectUriViolation extends AuthDomainViolation {
+  readonly code = 'OAUTH_REDIRECT_URI_INVALID';
+  readonly message = 'Redirect URI is invalid or insecure';
+
+  public static create(props: { redirectUri: string }) {
+    return new InvalidRedirectUriViolation(props);
+  }
+}

package/src/domain/policy/contracts/auth-policy-context.ts

@@ -0,0 +1,27 @@
+import { AuthMethod, IdentityId } from '@/domain/identity/value-objects';
+
+/**
+ * Immutable context passed to all authentication policies.
+ * Represents facts, not decisions.
+ */
+export type AuthPolicyContext = Readonly<{
+  readonly identityId?: IdentityId;
+  readonly method: AuthMethod;
+
+  /**
+   * Pre-calculated risk score (0-100).
+   * Produced by an upstream adapter (not domain logic).
+   */
+  readonly riskScore?: number;
+
+  /**
+   * Whether the identity is already known to be blocked.
+   */
+  readonly isBlocked?: boolean;
+
+  /**
+   * True if this authentication attempt is coming
+   * from a previously trusted environment.
+   */
+  readonly isTrustedDevice?: boolean;
+}>;

package/src/domain/policy/contracts/auth-policy-decision.ts

@@ -0,0 +1,7 @@
+/**
+ * Final decision produced by the policy engine.
+ * This object is immutable and side-effect free.
+ */
+export type AuthPolicyDecision =
+  | { readonly allowed: false; readonly reason: string }
+  | { readonly allowed: true; readonly requiresStepUp: boolean };

package/src/domain/policy/contracts/auth-policy.ts

@@ -0,0 +1,17 @@
+import { AuthPolicyDecision } from './auth-policy-decision';
+import { AuthPolicyContext } from './auth-policy-context';
+
+/**
+ * Authentication policy contract.
+ * A policy evaluates context and returns a partial decision.
+ */
+export abstract class AuthPolicyEvaluator {
+  /**
+   * Evaluates the policy against the given context.
+   *
+   * Returning `null` means:
+   * - this policy is not applicable
+   * - it has no opinion
+   */
+  abstract evaluate(context: AuthPolicyContext): AuthPolicyDecision | null;
+}

package/src/domain/policy/contracts/index.ts

@@ -0,0 +1,3 @@
+export * from './auth-policy';
+export * from './auth-policy-context';
+export * from './auth-policy-decision';

package/src/domain/policy/engine/auth-policy-engine.ts

@@ -0,0 +1,41 @@
+import { AuthPolicyDecision } from '../contracts/auth-policy-decision';
+import { AuthPolicyContext } from '../contracts/auth-policy-context';
+import { AuthPolicyEvaluator } from '../contracts/auth-policy';
+
+/**
+ * Coordinates multiple authentication policies
+ * and produces a final decision.
+ */
+export class AuthPolicyEngine {
+  private readonly policies: readonly AuthPolicyEvaluator[];
+
+  constructor(policies: readonly AuthPolicyEvaluator[]) {
+    this.policies = policies;
+  }
+
+  /**
+   * Evaluates all policies in order.
+   * First hard-deny wins.
+   */
+  public evaluate(context: AuthPolicyContext): AuthPolicyDecision {
+    let requiresStepUp = false;
+
+    for (const policy of this.policies) {
+      const decision = policy.evaluate(context);
+      if (!decision) continue;
+
+      if (decision.allowed === false) {
+        return decision;
+      }
+
+      if (decision.requiresStepUp) {
+        requiresStepUp = true;
+      }
+    }
+
+    return {
+      requiresStepUp,
+      allowed: true,
+    };
+  }
+}

package/src/domain/policy/index.ts

@@ -0,0 +1,2 @@
+export * from './contracts';
+export * from './engine/auth-policy-engine';

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

@@ -0,0 +1,82 @@
+import { SessionToken } from '@/domain/token/value-objects/session-token.vo';
+import { defaultIfNilOrEmpty } from '@/utils/default-if-blank.util';
+import { CreateEntityProps, Entity } from '@rineex/ddd';
+import { IdentityId } from '@/domain/identity';
+
+import { SessionId } from '../value-objects/session-id.vo';
+
+interface CreateSessionProps extends CreateEntityProps<SessionId> {
+  readonly identityId: IdentityId;
+  readonly token: SessionToken;
+  readonly expiresAt: Date;
+  readonly revokedAt?: Date;
+}
+
+export class Session extends Entity<SessionId> {
+  private _identityId: IdentityId;
+  private _token: SessionToken;
+  private _expiresAt: Date;
+  private _revokedAt?: Date;
+
+  protected constructor({ createdAt, id, ...props }: CreateSessionProps) {
+    super({ createdAt, id });
+
+    this._expiresAt = props.expiresAt;
+    this._revokedAt = props.revokedAt;
+    this._identityId = props.identityId;
+    this._token = props.token;
+  }
+
+  public static create(props: CreateSessionProps): Session {
+    return new Session(props);
+  }
+
+  toObject(): Record<string, unknown> {
+    return {
+      identityId: this._identityId.getValue(),
+      revokedAt: this._revokedAt?.toString(),
+      expiresAt: this._expiresAt.toString(),
+      revoked: !!this._revokedAt,
+      id: this.id.getValue(),
+      token: this._token,
+    };
+  }
+
+  revoke(at: Date): void {
+    if (this._revokedAt) return;
+
+    this.mutate(draft => {
+      draft._revokedAt = at;
+    });
+  }
+
+  public isActive(now = new Date()): boolean {
+    if (this._revokedAt) return false;
+
+    return now < this._expiresAt;
+  }
+
+  protected snapshot() {
+    return {
+      revokedAt: defaultIfNilOrEmpty(this._revokedAt?.toISOString()),
+      expiresAt: this._expiresAt.toISOString(),
+      identityId: this._identityId.toJSON(),
+      token: this._token.toJSON(),
+    };
+  }
+
+  protected restore(snapshot: Record<string, unknown>): void {
+    this._revokedAt = snapshot?.revokedAt
+      ? new Date(snapshot.revokedAt as string)
+      : undefined;
+    this._expiresAt = new Date(snapshot.expiresAt as string);
+    this._identityId = IdentityId.create(snapshot.identityId as string);
+    this._token = SessionToken.create(snapshot.token as string);
+  }
+
+  validate(): void {
+    if (this._expiresAt <= new Date(0)) {
+      throw new Error('Session expiration must be valid');
+    }
+  }
+}

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

@@ -0,0 +1,10 @@
+import { InvalidSessionViolation } from '@/domain/violations/invalid-session.violation';
+import { PrimitiveValueObject } from '@rineex/ddd';
+
+export class SessionId extends PrimitiveValueObject<string> {
+  protected validate(value: string): void {
+    if (!value || value.length < 16) {
+      throw InvalidSessionViolation.create();
+    }
+  }
+}