@api-client/core 0.18.57 → 0.18.58

package/src/modeling/actions/UpdateAction.ts

@@ -0,0 +1,41 @@
+import { Action, type ActionSchema } from './Action.js'
+import { observed, toRaw } from '../../decorators/observed.js'
+
+/**
+ * Enables modifying an existing resource.
+ * Endpoints: PUT or PATCH /[entity-collection-name]/{id}
+ */
+export interface UpdateActionSchema extends ActionSchema {
+  kind: 'update'
+  /**
+   * The allowed HTTP methods for updates. Default: PATCH only.
+   *
+   * These two methods represent the two common ways to update a resource:
+   * - PUT: Replaces the entire resource with the provided data.
+   * - PATCH: Applies a partial update to the resource, allowing for specific fields to be modified.
+   */
+  allowedMethods: ('PUT' | 'PATCH')[]
+}
+
+/**
+ * Enables modifying an existing resource.
+ * Endpoints: PUT or PATCH /[entity-collection-name]/{id}
+ */
+export class UpdateAction extends Action implements UpdateActionSchema {
+  @observed() override accessor kind: 'update'
+  @observed({ deep: true }) accessor allowedMethods: ('PUT' | 'PATCH')[]
+
+  constructor(state: Partial<UpdateActionSchema> = {}) {
+    super(state)
+    this.kind = 'update'
+    this.allowedMethods = state.allowedMethods ? [...state.allowedMethods] : ['PATCH']
+  }
+
+  override toJSON(): UpdateActionSchema {
+    return {
+      ...(super.toJSON() as UpdateActionSchema),
+      kind: 'update',
+      allowedMethods: structuredClone(toRaw(this, this.allowedMethods)) as ('PUT' | 'PATCH')[],
+    }
+  }
+}

package/src/modeling/rules/AccessRule.ts

@@ -0,0 +1,29 @@
+export interface AccessRuleSchema {
+  /**
+   * The unique identifier for the access rule.
+   * This is used to reference the rule in the API configuration.
+   */
+  type: string
+}
+
+/**
+ * Base class for all access rules.
+ */
+export class AccessRule extends EventTarget implements AccessRuleSchema {
+  readonly type: string
+
+  constructor(state: Partial<AccessRuleSchema> = {}) {
+    super()
+    this.type = state.type ?? ''
+  }
+
+  toJSON(): AccessRuleSchema {
+    return {
+      type: this.type,
+    }
+  }
+
+  notifyChange() {
+    this.dispatchEvent(new Event('change'))
+  }
+}

package/src/modeling/rules/AllowAuthenticated.ts

@@ -0,0 +1,24 @@
+import { AccessRule, type AccessRuleSchema } from './AccessRule.js'
+
+/**
+ * The action is allowed for any authenticated user.
+ * This rule does not impose any additional restrictions based on user properties or resource ownership.
+ * It is used for resources that should be accessible to all logged-in users.
+ */
+export interface AllowAuthenticatedAccessRuleSchema extends AccessRuleSchema {
+  type: 'authenticated'
+}
+
+/**
+ * The action is allowed for any authenticated user.
+ * This rule does not impose any additional restrictions based on user properties or resource ownership.
+ * It is used for resources that should be accessible to all logged-in users.
+ */
+export class AllowAuthenticatedAccessRule extends AccessRule implements AllowAuthenticatedAccessRuleSchema {
+  override readonly type: 'authenticated'
+
+  constructor(state: Partial<AllowAuthenticatedAccessRuleSchema> = {}) {
+    super(state)
+    this.type = 'authenticated'
+  }
+}

package/src/modeling/rules/AllowPublic.ts

@@ -0,0 +1,24 @@
+import { AccessRule, type AccessRuleSchema } from './AccessRule.js'
+
+/**
+ * The action is allowed for all users, including unauthenticated ones.
+ * This is typically used for public APIs or resources that do not require authentication.
+ * It is the most permissive rule and should be used with caution.
+ */
+export interface AllowPublicAccessRuleSchema extends AccessRuleSchema {
+  type: 'public'
+}
+
+/**
+ * The action is allowed for all users, including unauthenticated ones.
+ * This is typically used for public APIs or resources that do not require authentication.
+ * It is the most permissive rule and should be used with caution.
+ */
+export class AllowPublicAccessRule extends AccessRule implements AllowPublicAccessRuleSchema {
+  override readonly type: 'public'
+
+  constructor(state: Partial<AllowPublicAccessRuleSchema> = {}) {
+    super(state)
+    this.type = 'public'
+  }
+}

package/src/modeling/rules/MatchEmailDomain.ts

@@ -0,0 +1,39 @@
+import { AccessRule, type AccessRuleSchema } from './AccessRule.js'
+import { observed, toRaw } from '../../decorators/observed.js'
+
+/**
+ * The action is allowed if the authenticated user's email domain matches a specific domain.
+ * This is used to restrict access based on the user's email address.
+ * For example, only users with an email address from "my-company.com" can access certain resources.
+ */
+export interface MatchEmailDomainAccessRuleSchema extends AccessRuleSchema {
+  type: 'matchEmailDomain'
+  /**
+   * The email domains that the authenticated user's email must match.
+   */
+  domains: string[]
+}
+
+/**
+ * The action is allowed if the authenticated user's email domain matches a specific domain.
+ * This is used to restrict access based on the user's email address.
+ * For example, only users with an email address from "my-company.com" can access certain resources.
+ */
+export class MatchEmailDomainAccessRule extends AccessRule implements MatchEmailDomainAccessRuleSchema {
+  override readonly type: 'matchEmailDomain'
+
+  @observed({ deep: true }) accessor domains: string[]
+
+  constructor(state: Partial<MatchEmailDomainAccessRuleSchema> = {}) {
+    super(state)
+    this.type = 'matchEmailDomain'
+    this.domains = state.domains ? [...state.domains] : []
+  }
+
+  override toJSON(): MatchEmailDomainAccessRuleSchema {
+    return {
+      ...(super.toJSON() as MatchEmailDomainAccessRuleSchema),
+      domains: structuredClone(toRaw(this, this.domains)) as string[],
+    }
+  }
+}

package/src/modeling/rules/MatchResourceOwner.ts

@@ -0,0 +1,43 @@
+import { AccessRule, type AccessRuleSchema } from './AccessRule.js'
+import { observed } from '../../decorators/observed.js'
+
+/**
+ * The action is allowed if the authenticated user's ID matches a specific property on the resource.
+ * This is typically used to restrict access to resources owned by the user.
+ * For example, a user can only access their own profile or documents.
+ */
+export interface MatchResourceOwnerAccessRuleSchema extends AccessRuleSchema {
+  type: 'resourceOwner'
+  /**
+   * The property on the resource that should match the authenticated user's ID.
+   * This is typically the ID of the user who owns the resource.
+   *
+   * The domain model should annotate this property with the "ResourceOwnerIdentifier" semantic
+   * to indicate that it is used for ownership checks.
+   */
+  property: string
+}
+
+/**
+ * The action is allowed if the authenticated user's ID matches a specific property on the resource.
+ * This is typically used to restrict access to resources owned by the user.
+ * For example, a user can only access their own profile or documents.
+ */
+export class MatchResourceOwnerAccessRule extends AccessRule implements MatchResourceOwnerAccessRuleSchema {
+  override readonly type: 'resourceOwner'
+
+  @observed() accessor property: string
+
+  constructor(state: Partial<MatchResourceOwnerAccessRuleSchema> = {}) {
+    super(state)
+    this.type = 'resourceOwner'
+    this.property = state.property ?? ''
+  }
+
+  override toJSON(): MatchResourceOwnerAccessRuleSchema {
+    return {
+      ...(super.toJSON() as MatchResourceOwnerAccessRuleSchema),
+      property: this.property,
+    }
+  }
+}

package/src/modeling/rules/MatchUserProperty.ts

@@ -0,0 +1,44 @@
+import { AccessRule, type AccessRuleSchema } from './AccessRule.js'
+import { observed } from '../../decorators/observed.js'
+
+/**
+ * The action is allowed if a specific property on the authenticated user matches an expected value.
+ * This is used to enforce other user-specific restrictions.
+ */
+export interface MatchUserPropertyAccessRuleSchema extends AccessRuleSchema {
+  type: 'matchUserProperty'
+  /**
+   * The property on the authenticated user that should match the expected value.
+   */
+  property: string
+  /**
+   * The expected value for the user property.
+   */
+  value: string
+}
+
+/**
+ * The action is allowed if a specific property on the authenticated user matches an expected value.
+ * This is used to enforce other user-specific restrictions.
+ */
+export class MatchUserPropertyAccessRule extends AccessRule implements MatchUserPropertyAccessRuleSchema {
+  override readonly type: 'matchUserProperty'
+
+  @observed() accessor property: string
+  @observed() accessor value: string
+
+  constructor(state: Partial<MatchUserPropertyAccessRuleSchema> = {}) {
+    super(state)
+    this.type = 'matchUserProperty'
+    this.property = state.property ?? ''
+    this.value = state.value ?? ''
+  }
+
+  override toJSON(): MatchUserPropertyAccessRuleSchema {
+    return {
+      ...(super.toJSON() as MatchUserPropertyAccessRuleSchema),
+      property: this.property,
+      value: this.value,
+    }
+  }
+}

package/src/modeling/rules/MatchUserRole.ts

@@ -0,0 +1,43 @@
+import { AccessRule, type AccessRuleSchema } from './AccessRule.js'
+import { observed, toRaw } from '../../decorators/observed.js'
+
+/**
+ * The action is allowed if the authenticated user has a specific role.
+ * This is used to enforce role-based access control (RBAC).
+ * For example, only users with the "admin" role can perform certain actions.
+ */
+export interface MatchUserRoleAccessRuleSchema extends AccessRuleSchema {
+  type: 'matchUserRole'
+  /**
+   * The role that the authenticated user must have to access the resource.
+   * This is typically a property on the user entity that defines their role.
+   *
+   * The domain model should annotate this property with the "UserRole" semantic
+   * to indicate that it is used for role-based access control.
+   */
+  role: string[]
+}
+
+/**
+ * The action is allowed if the authenticated user has a specific role.
+ * This is used to enforce role-based access control (RBAC).
+ * For example, only users with the "admin" role can perform certain actions.
+ */
+export class MatchUserRoleAccessRule extends AccessRule implements MatchUserRoleAccessRuleSchema {
+  override readonly type: 'matchUserRole'
+
+  @observed({ deep: true }) accessor role: string[]
+
+  constructor(state: Partial<MatchUserRoleAccessRuleSchema> = {}) {
+    super(state)
+    this.type = 'matchUserRole'
+    this.role = state.role ? [...state.role] : []
+  }
+
+  override toJSON(): MatchUserRoleAccessRuleSchema {
+    return {
+      ...(super.toJSON() as MatchUserRoleAccessRuleSchema),
+      role: structuredClone(toRaw(this, this.role)) as string[],
+    }
+  }
+}

package/src/modeling/rules/RateLimitRule.ts

@@ -0,0 +1,104 @@
+import { observed, toRaw } from '../../decorators/observed.js'
+
+export type RateLimitRuleKey = { type: 'ip' } | { type: 'userId' } | { type: 'role'; value: string }
+export type RateLimitRuleInterval = 'second' | 'minute' | 'hour' | 'day'
+
+/**
+ * Represents a single rate limiting rule that applies to a specific
+ * type of client, using a token bucket algorithm.
+ */
+export interface RateLimitRuleSchema {
+  /**
+   * A human-readable description of what this rule is for.
+   * e.g., "Limit anonymous users to 60 requests per hour."
+   */
+  description?: string
+
+  /**
+   * Defines how to group requests for rate limiting. This determines
+   * who the limit applies to.
+   *
+   * - 'ip': Keys on the client's IP address. Best for anonymous traffic.
+   * - 'userId': Keys on the authenticated user's ID. Best for logged-in users.
+   * - 'role': Applies a shared limit to all users of a specific role.
+   */
+  key?: RateLimitRuleKey
+
+  /**
+   * The number of requests allowed over the defined interval.
+   * This is the rate at which tokens are added to the bucket.
+   */
+  rate?: number
+
+  /**
+   * The time interval for the rate.
+   */
+  interval?: RateLimitRuleInterval
+
+  /**
+   * The maximum number of requests that can be made in a burst.
+   * This represents the "bucket size." A larger burst allows for
+   * more requests to be made in a short period before throttling begins.
+   */
+  burst?: number
+}
+
+/**
+ * Represents a single rate limiting rule that applies to a specific
+ * type of client, using a token bucket algorithm.
+ */
+export class RateLimitRule extends EventTarget implements RateLimitRuleSchema {
+  @observed() accessor description: string | undefined
+  @observed({ deep: true }) accessor key: RateLimitRuleKey | undefined
+  @observed() accessor rate: number | undefined
+  @observed() accessor interval: RateLimitRuleInterval | undefined
+  @observed() accessor burst: number | undefined
+
+  constructor(state: Partial<RateLimitRuleSchema> = {}) {
+    super()
+    this.description = state.description
+    this.key = RateLimitRule.isRateLimitRuleKey(state.key) ? structuredClone(state.key) : undefined
+    this.rate = typeof state.rate === 'number' ? state.rate : undefined
+    this.interval = RateLimitRule.isRateLimitRuleInterval(state.interval) ? state.interval : undefined
+    this.burst = typeof state.burst === 'number' ? state.burst : undefined
+  }
+
+  toJSON(): RateLimitRuleSchema {
+    const result: RateLimitRuleSchema = {}
+    if (this.description) {
+      result.description = this.description
+    }
+    if (RateLimitRule.isRateLimitRuleKey(this.key)) {
+      result.key = structuredClone(toRaw(this, this.key))
+    }
+    if (typeof this.rate === 'number') {
+      result.rate = this.rate
+    }
+    if (RateLimitRule.isRateLimitRuleInterval(this.interval)) {
+      result.interval = this.interval
+    }
+    if (typeof this.burst === 'number') {
+      result.burst = this.burst
+    }
+    return result
+  }
+
+  notifyChange() {
+    this.dispatchEvent(new Event('change'))
+  }
+
+  static isRateLimitRuleInterval(value: unknown): value is RateLimitRuleInterval {
+    if (typeof value !== 'string') {
+      return false
+    }
+    return ['second', 'minute', 'hour', 'day'].includes(value)
+  }
+
+  static isRateLimitRuleKey(value: unknown): value is RateLimitRuleKey {
+    if (typeof value !== 'object' || value === null) {
+      return false
+    }
+    const key = value as Record<string, unknown>
+    return 'type' in key && (key.type === 'ip' || key.type === 'userId' || key.type === 'role')
+  }
+}

package/src/modeling/rules/RateLimitingConfiguration.ts

@@ -0,0 +1,32 @@
+import { RateLimitRule, type RateLimitRuleSchema } from './RateLimitRule.js'
+import { observed } from '../../decorators/observed.js'
+
+/**
+ * Defines the rate limiting and throttling policies for the entire API.
+ */
+export interface RateLimitingConfigurationSchema {
+  /**
+   * An ordered list of rules. The first rule that matches an incoming
+   * request will be applied.
+   */
+  rules: RateLimitRuleSchema[]
+}
+
+export class RateLimitingConfiguration extends EventTarget implements RateLimitingConfigurationSchema {
+  @observed({ deep: true }) accessor rules: RateLimitRule[]
+
+  constructor(state: Partial<RateLimitingConfigurationSchema> = {}) {
+    super()
+    this.rules = state.rules?.map((rule) => new RateLimitRule(rule)) || []
+  }
+
+  toJSON(): RateLimitingConfigurationSchema {
+    return {
+      rules: this.rules.map((rule) => rule.toJSON()),
+    }
+  }
+
+  notifyChange() {
+    this.dispatchEvent(new Event('change'))
+  }
+}