Pristine Bootstrap Authentication

Overview

The platform uses a system setting called auth_mode to manage the initial administrator account creation process. This mechanism solves the "first user" problem for a new platform instance or a new tenant: how to securely designate the first administrator without pre-provisioning credentials.

The system supports two authentication modes:

• pristine: The initial state for a new, unconfigured system or tenant. In this mode, the first user who successfully authenticates is automatically pro<customer>ed to an administrator. The system then immediately and atomically transitions to protected mode.
• protected: The standard operational mode. The system enforces Role-Based Access Control (RBAC) for all users. Unauthenticated users or users without assigned roles are denied access.

This component provides methods to query the current mode and to perform the atomic pro<customer>ion-and-transition operation. The process is designed to be race-safe, ensuring that even with concurrent first-login attempts, only one user becomes the administrator. Operations are tenant-scoped to ensure data isolation in multi-tenant environments.

How it Works

The core logic resides in the AuthModeRepository, which interacts directly with the s2r_system_setting table in the database.

Authentication Modes

The auth_mode is a tenant-scoped setting with two possible values:

If the auth_mode setting is missing from the database for any reason, the system defensively defaults to protected mode to maintain a secure state.

Initial Administrator Pro<customer>ion

For a single-tenant deployment or the first bootstrap of the system, the pro<customer>eIfPristine method handles the initial administrator creation. This process is designed to be atomic and safe against race conditions.

When the first user attempts to log in to a pristine system, the following sequence occurs within a single database transaction:

1. Acquire Lock: The system acquires a transaction-scoped PostgreSQL advisory lock using pg_advisory_xact_lock. This lock acts as a mutex, serializing all concurrent attempts to perform the bootstrap. The lock key is a stable, predefined 64-bit integer (0x53324153_55544830).
2. Verify Mode: Inside the locked transaction, the system re-reads the auth_mode setting with a FOR UPDATE clause.
   • The first process to acquire the lock will read pristine.
   • Any subsequent, concurrent processes will block until the first one commits. By then, the mode will have been changed to protected, so they will read the new value and perform no action.
3. Pro<customer>e and Transition: If the mode is pristine, the system performs two actions:
   • It creates a role binding, assigning the admin role to the authenticating user's email.
   • It updates the auth_mode setting to protected.
4. Release Lock: The transaction is committed, and the advisory lock is automatically released.

This ensures that only one of potentially many concurrent first-time login attempts succeeds in becoming the administrator.

sequenceDiagram
    participant User as First Admin User
    participant Platform as Platform Authentication
    participant Database

    User->>Platform: Authenticates for the first time
    Platform->>Database: BEGIN TRANSACTION
    Platform->>Database: SELECT pg_advisory_xact_lock(0x5332415355544830)
    Note over Platform,Database: Lock acquired. Concurrent attempts are blocked.
    Platform->>Database: SELECT auth_mode FROM s2r_system_setting FOR UPDATE
    Database-->>Platform: Returns 'pristine'
    Platform->>Database: INSERT role binding for user (role: 'admin')
    Platform->>Database: UPDATE s2r_system_setting SET auth_mode = 'protected'
    Platform->>Database: COMMIT
    Note over Platform,Database: Transaction commits, lock is released.
    Platform-->>User: Login successful (now an admin)

Multi-Tenant Bootstrap

In a multi-tenant (SaaS) environment, each tenant has its own auth_mode lifecycle. The bootstrapTenantAdmin method facilitates this, providing an idempotent and race-safe way to provision the first administrator for a specific tenant.

The process is similar to the single-tenant pro<customer>ion but with key differences:

1. Per-Tenant Locking: Instead of a global lock, a per-tenant advisory lock is used. The lock key is a 64-bit hash generated from a namespace (s2r-saas-tenant-admin-bootstrap) and the target tenantId. This allows different tenants to be bootstrapped concurrently, while requests for the same tenant are serialized.
2. Pristine State Seeding: The method first attempts to INSERT a pristine auth_mode setting for the tenant, using ON CONFLICT DO NOTHING. This ensures that a new tenant starts in the correct state but does not affect tenants that already have an auth_mode set (in any state).
3. Scoped Pro<customer>ion: If the tenant's mode is pristine, the specified adminEmail is bound to the admin role, and the tenant's auth_mode is flipped to protected. All database operations are confined to the target tenant.

This flow is replay-safe; if a tenant is already in protected mode, the operation is a no-op and it will never override an existing tenant administrator.

Changing Modes

The programmatic API is designed for a one-way transition from pristine to protected. Downgrading a system or tenant from protected back to pristine is intentionally not exposed through the API. This is a security measure to prevent accidental or malicious re-opening of the bootstrap mechanism.

To reset the mode to pristine, an operator must perform a direct UPDATE on the s2r_system_setting table in the database.

API Reference

The component exposes its functionality as methods on the AuthModeRepository class.

currentMode()

Returns the current auth_mode for the bound tenant.

• Returns: String — Either "pristine" or "protected". It defensively returns "protected" if the setting row is missing from the database.

pro<customer>eIfPristine(String actorEmail)

Attempts to pro<customer>e the specified user to admin if the system is in pristine mode. This is the primary method for single-tenant bootstrap.

• Parameters:

  Name	Type	Description
  actorEmail	String	The email address of the user to pro<customer>e.

• Returns: boolean — true if the pro<customer>ion was successful (the mode was pristine). false if the mode was already protected or if the input was invalid (e.g., null or malformed email).

bootstrapTenantAdmin(UUID tenantId, String adminEmail)

Seeds the first administrator for a specific tenant in a multi-tenant environment. This method is idempotent and race-safe.

• Parameters:

  Name	Type	Description
  tenantId	UUID	The unique identifier for the tenant to bootstrap.
  adminEmail	String	The email address of the user to designate as admin.

• Returns: boolean — true if this call successfully seeded the admin (the tenant's mode was pristine). false if the tenant was already protected or if inputs were invalid.

setMode(String mode)

Forcibly sets the auth_mode to a specified value. It will either update an existing row or insert a new one.

• Parameters:

  Name	Type	Description
  mode	String	The desired mode, either "pristine" or "protected".

• Throws: IllegalArgumentException if the provided mode is not one of the two valid values.

Troubleshooting

Pro<customer>ion or Bootstrap is a No-Op

• Symptom: Calling pro<customer>eIfPristine or bootstrapTenantAdmin returns false and no administrator is created.
• Cause: This typically means the system or tenant was already in protected mode when the call was made. In a race condition, another process likely completed the bootstrap first. It can also be caused by invalid input, such as a null, blank, or malformed email address.

Missing Tenant Context

• Symptom: An attempt to call bootstrapTenantAdmin fails or affects the wrong tenant.
• Cause: The caller did not bind the correct tenantId to the TenantContext before calling the method. All operations are scoped by a connection-level parameter that relies on this context being set.

Invalid Mode Error

• Symptom: Calling setMode throws an IllegalArgumentException.
• Cause: The mode string passed to the method was not exactly pristine or protected (case-insensitive).

See Also

• Role-Based Access Control (RBAC): The protected mode relies on role bindings managed by the platform's RBAC system.
• System Settings: The auth_mode is one of several configurable system settings.
• Tenant Administration: The multi-tenant bootstrap is part of the larger tenant provisioning and management lifecycle.

All SOAP-to-REST docs