ARFC-1005: Self-Joinable Realms

Status

Abstract

This RFC proposes adding self-join capability to realms, allowing users to join “open” realms without requiring an administrator invitation. This enables new platform users to discover and join realms (and subsequently teams within those realms) through a streamlined onboarding flow.

Table of Contents

1. Introduction
2. Motivation
3. Specification
   • 3.1 Schema Changes
   • 3.2 Self-Join Eligibility Rules
   • 3.3 API Endpoints
   • 3.4 Validation Rules
4. Security Considerations
5. Backward Compatibility
6. References

1. Introduction

The ĀYŌDÈ platform organizes users into hierarchical realms. Currently, realm membership requires an administrator to explicitly add users via invitation or direct assignment. This creates friction for open competitions and public programs where users should be able to self-enroll.

This RFC introduces a isSelfJoinable flag on realms that, when enabled, allows eligible users to join without administrator intervention.

2. Motivation

Current State

• Users must be invited or added by realm administrators
• New users cannot independently join realms to participate in competitions
• Teams (per ARFC-1004) require realm membership, creating a chicken-and-egg problem for open competitions

Use Cases

1. Open Competitions: Flight Path and similar competitions need to allow any registered platform user to join the competition realm and form/join teams
2. Public Programs: Educational programs may want open enrollment at certain levels
3. Hierarchical Access: A school district realm may be invite-only, but individual school realms within it may allow self-join for verified students

Design Goals

1. Simple flag: Single boolean column, no complex configuration
2. Hierarchical awareness: Self-join rules differ based on realm position in hierarchy
3. No privilege escalation: Self-joining grants basic membership only, not administrative access
4. Audit trail: All self-join actions are logged via standard audit columns

3. Specification

3.1 Schema Changes

Add one column to the existing Realms table:

Column Definition:

Derived Property:

isSelfJoinable := (selfJoinRoleID is not null)

A realm is self-joinable if and only if it has a selfJoinRoleID configured. This eliminates redundancy and ensures that self-joinable realms always grant meaningful privileges.

Design Rationale:

Following the PreconfiguredPositionAssignments pattern, self-joining must grant both:

1. RealmMembership — access to the realm
2. RoleMembership — privileges within the realm (e.g., /team/join)

A self-joinable realm without a role would be useless — users could join but do nothing. By making selfJoinRoleID the single source of truth, we enforce that self-joinable realms always have an associated role.

Constraints:

• selfJoinRoleID must reference a role owned by the same realm (enforced by stored procedure)
• To make a realm self-joinable: set selfJoinRoleID to a valid role
• To disable self-join: set selfJoinRoleID = NULL

3.2 Self-Join Eligibility Rules

The eligibility to self-join a realm depends on whether the realm is a top-level realm or a descendant realm.

flowchart TB
    Start([User requests to join Realm]) --> CheckFlag{selfJoinRoleID IS NOT NULL?}
    CheckFlag -->|No| Reject([Reject: Realm is not self-joinable])
    CheckFlag -->|Yes| CheckLevel{Is Realm top-level?}

    CheckLevel -->|Yes| TopLevel[Top-Level Realm]
    CheckLevel -->|No| Descendant[Descendant Realm]

    TopLevel --> CheckPlatform{Is User a platform member?}
    CheckPlatform -->|Yes| AllowJoin([Allow: Add to RealmMembership])
    CheckPlatform -->|No| RejectNotPlatform([Reject: Not a platform user])

    Descendant --> FindRoot[Lookup topmost ancestor via RealmClosure]
    FindRoot --> CheckAncestor{Is User a member of topmost realm?}
    CheckAncestor -->|Yes| AllowJoin
    CheckAncestor -->|No| RejectNotInHierarchy([Reject: Not in realm hierarchy])

    style AllowJoin fill:#c8e6c9,color:#1b1a17
    style Reject fill:#ffcdd2,color:#1b1a17
    style RejectNotPlatform fill:#ffcdd2,color:#1b1a17
    style RejectNotInHierarchy fill:#ffcdd2,color:#1b1a17

Rule Summary

Topmost Ancestor Resolution

The RealmClosure table provides direct lookup of any ancestor without traversal. The topmost ancestor is the entry with maximum depth:

topmostRealmID := RealmClosure.lookup(
    descendantID = realmID,
    depth = MAX(depth for this descendant)
).ancestorID

Note: RealmClosure contains pre-computed ancestor-descendant pairs for all depths, enabling O(1) hierarchy lookups.

Membership Check for Descendant Realms

isMember := exists(RealmMembership where realmID = topmostRealmID and userID = user)

3.3 API Endpoints

New Endpoints

Note: The ~ path segment is a self-referential identifier representing the authenticated user. The relationship query parameter filters the user’s relationship to realms:

• member: Realms the user belongs to
• joinable: Self-joinable realms the user is eligible to join but is not yet a member of

Modified Endpoints

Endpoint Details

GET /v1/users/~/realms

Returns realms based on the user’s relationship to them.

Query parameters:

• relationship (required): member

  joinable

  • member: Realms the user is currently a member of
  • joinable: Self-joinable realms the user is eligible to join (excludes current memberships)

Response:

{
  "envelope": { "status": "success", "requestID": "..." },
  "data": [
    {
      "eidURN": "urn:ayode:realm-eid:uuid",
      "name": "Flight Path 2026",
      "description": "Open competition realm",
      "isSelfJoinable": true,
      "selfJoinRoleEIDURN": "urn:ayode:role-eid:uuid",
      "isTopLevel": true,
      "relationship": "joinable"
    }
  ]
}

Note: isSelfJoinable is derived from selfJoinRoleID IS NOT NULL and included for convenience.

POST /v1/realms/{realm-eid}/members/~

Self-join request. No request body required.

Success response (201 Created):

{
  "envelope": { "status": "success", "requestID": "..." },
  "data": {
    "membershipEIDURN": "urn:ayode:realm-membership-eid:uuid",
    "realmEIDURN": "urn:ayode:realm-eid:uuid",
    "joinedAt": "2026-02-25T12:00:00.000000Z"
  }
}

Error responses:

• 403 Forbidden: Realm is not self-joinable or user is not eligible
• 409 Conflict: User is already a member

DELETE /v1/realms/{realm-eid}/members/~

Leave a realm. No request body required.

Success response (200 OK):

{
  "envelope": { "status": "success", "requestID": "..." },
  "data": {
    "realmEIDURN": "urn:ayode:realm-eid:uuid",
    "leftAt": "2026-02-25T14:30:00.000000Z"
  }
}

Error responses:

• 404 Not Found: User is not a member of this realm
• 403 Forbidden: User cannot leave (e.g., sole administrator)

3.4 Validation Rules

Self-Join Validation

The api_realmSelfJoin_v1 stored procedure enforces the following checks:

1. Realm must be self-joinable (selfJoinRoleID IS NOT NULL)
2. User cannot already be a member (check RealmMembership)
3. Descendant realm eligibility (user must be member of topmost ancestor)

Topmost ancestor lookup:

topmostRealmID := RealmClosure.lookup(descendantID = realmID, depth = MAX).ancestorID

On successful self-join, insert into both tables:

• RealmMembership — grants realm access
• RoleMembership — grants privileges via selfJoinRoleID

Constraints Enforced by Stored Procedures

4. Security Considerations

Controlled Privilege Assignment

Self-joining grants:

1. RealmMembership — access to the realm
2. RoleMembership — assignment to selfJoinRoleID (if configured)

Privilege boundaries:

• Users receive only the privileges defined in selfJoinRoleID
• The role should be a limited “Participant” or “Member” role with basic privileges
• Administrative privileges (e.g., /realm/update, /team/manage) should NOT be granted via self-join roles
• Realm administrators control which role is assigned by setting selfJoinRoleID

Recommended self-join role privileges:

• urn:ayode:privilege-action:/team/list — view teams
• urn:ayode:privilege-action:/team/join — apply to join teams
• urn:ayode:privilege-action:/season/list — view seasons
• urn:ayode:privilege-action:/season/read — view season details

Audit Trail

All self-join actions are tracked via:

• createdByUserID = p_userID (user who joined)
• createdTimestamp (when they joined)

This distinguishes self-joins from admin-initiated additions where createdByUserID would be the admin.

Rate Limiting

The POST /v1/realms/{realm-eid}/members/~ endpoint should be rate-limited to prevent abuse:

• Recommended: 10 join requests per user per minute
• Prevents automated realm-hopping or membership spam

Realm Discovery

The GET /v1/realms/self-joinable endpoint only returns realms the user is eligible to join:

• Top-level self-joinable realms are discoverable by all users
• Descendant self-joinable realms are only discoverable by users already in the hierarchy

This prevents information leakage about realm structures.

5. Backward Compatibility

This RFC is additive and backward compatible:

• New column: isSelfJoinable added to Realms table
  • Existing realms will need a migration to set initial value (recommend FALSE)
• New endpoints: Three new API endpoints added
• Modified endpoints: Existing realm endpoints extended to include new field
• No breaking changes: Existing realm management workflows unchanged

Migration

Add selfJoinRoleID column to Realms table:

• Type: INT, nullable
• Foreign key reference to Roles(id)
• Existing realms default to NULL (not self-joinable)

6. References

Related ARFCs

• ARFC-1004: Teams, Leagues, Seasons, and Competitive Gaming Schema

Related Schema

• Realms table: Target table for isSelfJoinable column
• RealmClosure table: Pre-computed ancestor/descendant pairs for direct hierarchy lookups
• RealmMembership table: Target table for self-join records

Summary

Author

ĀYŌDÈ Development Team Codermerlin Academy Architecture