[PM-34387] Add organization invite link creation endpoint

src/Api/AdminConsole/Controllers/BaseAdminConsoleController.cs

@@ -3,23 +3,34 @@
 using Bit.Core.Models.Api;
 using Microsoft.AspNetCore.Http.HttpResults;
 using Microsoft.AspNetCore.Mvc;
+using CommandError = Bit.Core.AdminConsole.Utilities.v2.Error;
 
 namespace Bit.Api.AdminConsole.Controllers;
 
 public abstract class BaseAdminConsoleController : Controller
 {
+    /// <summary>
+    /// Maps a void <see cref="CommandResult"/> to an HTTP response.
+    /// Returns 204 No Content on success, or the appropriate error status code on failure.
+    /// </summary>
     protected static IResult Handle(CommandResult commandResult) =>
         commandResult.Match<IResult>(
-            error => error switch
-            {
-                BadRequestError badRequest => Error.BadRequest(badRequest.Message),
-                NotFoundError notFound => Error.NotFound(notFound.Message),
-                InternalError internalError => Error.InternalError(internalError.Message),
-                _ => Error.InternalError(error.Message)
-            },
+            error => MapError(error),
             _ => TypedResults.NoContent()
         );
 
+    /// <summary>
+    /// Maps a <see cref="CommandResult{T}"/> to an HTTP response.
+    /// On success, delegates to <paramref name="success"/> so the caller can choose the response shape
+    /// (e.g. <c>TypedResults.Created</c> for POST, <c>TypedResults.Ok</c> for GET/PUT).
+    /// On failure, returns the appropriate error status code.
+    /// </summary>
+    protected static IResult Handle<T>(CommandResult<T> commandResult, Func<T, IResult> success) =>
+        commandResult.Match<IResult>(
+            error => MapError(error),
+            success
+        );
+
     protected static class Error
     {
         public static NotFound<ErrorResponseModel> NotFound(string message = "Resource not found.") =>
@@ -37,4 +48,21 @@ public static JsonHttpResult<ErrorResponseModel> InternalError(
                 new ErrorResponseModel(message),
                 statusCode: StatusCodes.Status500InternalServerError);
     }
+
+    private static IResult MapError(CommandError error) =>
+        error switch
+        {
+            BadRequestError badRequest => TypedResults.BadRequest(new ErrorResponseModel(badRequest.Message)),
+            NotFoundError notFound => TypedResults.NotFound(new ErrorResponseModel(notFound.Message)),
+            ConflictError conflict => TypedResults.Json(
+                new ErrorResponseModel(conflict.Message),
+                statusCode: StatusCodes.Status409Conflict),
+            InternalError internalError => TypedResults.Json(
+                new ErrorResponseModel(internalError.Message),
+                statusCode: StatusCodes.Status500InternalServerError),
+            _ => TypedResults.Json(
+                new ErrorResponseModel(error.Message),
+                statusCode: StatusCodes.Status500InternalServerError
+            )
+        };
 }

src/Api/AdminConsole/Controllers/OrganizationInviteLinksController.cs

@@ -0,0 +1,32 @@
+using Bit.Api.AdminConsole.Authorization;
+using Bit.Api.AdminConsole.Authorization.Requirements;
+using Bit.Api.AdminConsole.Models.Request.Organizations;
+using Bit.Api.AdminConsole.Models.Response.Organizations;
+using Bit.Core;
+using Bit.Core.AdminConsole.OrganizationFeatures.InviteLinks.Interfaces;
+using Bit.Core.Utilities;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Bit.Api.AdminConsole.Controllers;
+
+[Route("organizations/{orgId}/invite-link")]
+[Authorize("Application")]
+[RequireFeature(FeatureFlagKeys.GenerateInviteLink)]
+public class OrganizationInviteLinksController(
+    ICreateOrganizationInviteLinkCommand createOrganizationInviteLinkCommand)
+    : BaseAdminConsoleController
+{
+    [HttpPost("")]
+    [Authorize<ManageUsersRequirement>]
+    public async Task<IResult> Create(Guid orgId, [FromBody] CreateOrganizationInviteLinkRequestModel model)
+    {
+        var result = await createOrganizationInviteLinkCommand.CreateAsync(
+            model.ToCommandRequest(orgId));
+
+        return Handle(result, link =>
+            TypedResults.Created(
+                $"organizations/{orgId}/invite-link",
+                new OrganizationInviteLinkResponseModel(link)));
+    }
+}

src/Api/AdminConsole/Models/Request/Organizations/CreateOrganizationInviteLinkRequestModel.cs

@@ -0,0 +1,37 @@
+using System.ComponentModel.DataAnnotations;
+using Bit.Core.AdminConsole.OrganizationFeatures.InviteLinks;
+using Bit.Core.Utilities;
+
+namespace Bit.Api.AdminConsole.Models.Request.Organizations;
+
+public class CreateOrganizationInviteLinkRequestModel
+{
+    /// <summary>
+    /// Email domains permitted to accept the invite link (e.g. <c>["acme.com"]</c>).
+    /// </summary>
+    [Required]
+    [MinLength(1)]
+    [ValidateSequence<DomainNameValidatorAttribute>]
+    public required IEnumerable<string> AllowedDomains { get; set; }
+
+    /// <summary>
+    /// The invite key encrypted with the organization key.
+    /// </summary>
+    [Required]
+    [EncryptedString]
+    public required string EncryptedInviteKey { get; set; }
+
+    /// <summary>
+    /// The organization key encrypted for the invite link. Currently unused; will be populated in a future stage.
+    /// </summary>
+    [EncryptedString]
+    public string? EncryptedOrgKey { get; set; }
+
+    public CreateOrganizationInviteLinkRequest ToCommandRequest(Guid organizationId) => new()
+    {
+        OrganizationId = organizationId,
+        AllowedDomains = AllowedDomains,
+        EncryptedInviteKey = EncryptedInviteKey,
+        EncryptedOrgKey = EncryptedOrgKey,
+    };
+}

src/Api/AdminConsole/Models/Response/Organizations/OrganizationInviteLinkResponseModel.cs

@@ -0,0 +1,31 @@
+using Bit.Core.AdminConsole.Entities;
+using Bit.Core.Models.Api;
+
+namespace Bit.Api.AdminConsole.Models.Response.Organizations;
+
+public class OrganizationInviteLinkResponseModel : ResponseModel
+{
+    public OrganizationInviteLinkResponseModel() : base("organizationInviteLink") { }
+
+    public OrganizationInviteLinkResponseModel(OrganizationInviteLink inviteLink)
+        : base("organizationInviteLink")
+    {
+        ArgumentNullException.ThrowIfNull(inviteLink);
+
+        Id = inviteLink.Id;
+        Code = inviteLink.Code;
+        OrganizationId = inviteLink.OrganizationId;
+        AllowedDomains = inviteLink.GetAllowedDomains();
+        EncryptedInviteKey = inviteLink.EncryptedInviteKey;
+        EncryptedOrgKey = inviteLink.EncryptedOrgKey;
+        CreationDate = inviteLink.CreationDate;
+    }
+
+    public Guid Id { get; set; }
+    public Guid Code { get; set; }
+    public Guid OrganizationId { get; set; }
+    public IEnumerable<string> AllowedDomains { get; set; } = [];
+    public string EncryptedInviteKey { get; set; } = null!;
+    public string? EncryptedOrgKey { get; set; }
+    public DateTime CreationDate { get; set; }
+}

src/Core/AdminConsole/Entities/OrganizationInviteLink.cs

@@ -1,19 +1,32 @@
-using Bit.Core.Entities;
+using System.Text.Json;
+using Bit.Core.Entities;
 using Bit.Core.Utilities;
 
 namespace Bit.Core.AdminConsole.Entities;
 
 public class OrganizationInviteLink : ITableObject<Guid>
 {
     public Guid Id { get; set; }
-    public Guid Code { get; set; }
+    /// <summary>
+    /// A random, publicly shareable code used to identify the invite link.
+    /// Uses <see cref="Guid.NewGuid"/> rather than a sequential/comb GUID because this is not
+    /// a table identifier and therefore does not need index-friendly ordering. A comb GUID's embedded
+    /// timestamp would also make the code partially predictable.
+    /// </summary>
+    public Guid Code { get; set; } = Guid.NewGuid();
     public Guid OrganizationId { get; set; }
     public string AllowedDomains { get; set; } = null!;
     public string EncryptedInviteKey { get; set; } = null!;
     public string? EncryptedOrgKey { get; set; }
     public DateTime CreationDate { get; set; } = DateTime.UtcNow;
     public DateTime RevisionDate { get; set; } = DateTime.UtcNow;
 
+    public IEnumerable<string> GetAllowedDomains() =>
+        JsonSerializer.Deserialize<IEnumerable<string>>(AllowedDomains) ?? [];
+
+    public void SetAllowedDomains(IEnumerable<string> domains) =>
+        AllowedDomains = JsonSerializer.Serialize(domains);
+
     public void SetNewId()
     {
         if (Id == default)

src/Core/AdminConsole/OrganizationFeatures/InviteLinks/CreateOrganizationInviteLinkCommand.cs

@@ -0,0 +1,67 @@
+using Bit.Core.AdminConsole.Entities;
+using Bit.Core.AdminConsole.OrganizationFeatures.InviteLinks.Interfaces;
+using Bit.Core.AdminConsole.Repositories;
+using Bit.Core.AdminConsole.Utilities.v2.Results;
+using Bit.Core.Services;
+
+namespace Bit.Core.AdminConsole.OrganizationFeatures.InviteLinks;
+
+public class CreateOrganizationInviteLinkCommand(
+    IOrganizationInviteLinkRepository organizationInviteLinkRepository,
+    IApplicationCacheService applicationCacheService,
+    TimeProvider timeProvider)
+    : ICreateOrganizationInviteLinkCommand
+{
+    public async Task<CommandResult<OrganizationInviteLink>> CreateAsync(
+        CreateOrganizationInviteLinkRequest request)
+    {
+        if (!await OrganizationHasInviteLinksAbilityAsync(request.OrganizationId))
+        {
+            return new InviteLinkNotAvailable();
+        }
+
+        var sanitizedDomains = SanitizeDomains(request.AllowedDomains);
+        if (sanitizedDomains.Count == 0)
+        {
+            return new InviteLinkDomainsRequired();
+        }
+
+        var existingLink = await organizationInviteLinkRepository.GetByOrganizationIdAsync(request.OrganizationId);
+        if (existingLink != null)
+        {
+            return new InviteLinkAlreadyExists();
+        }
+
+        var now = timeProvider.GetUtcNow().UtcDateTime;
+        var inviteLink = new OrganizationInviteLink
+        {
+            OrganizationId = request.OrganizationId,
+            EncryptedInviteKey = request.EncryptedInviteKey,
+            EncryptedOrgKey = request.EncryptedOrgKey,
+            CreationDate = now,
+            RevisionDate = now,
+        };
+        inviteLink.SetAllowedDomains(sanitizedDomains);
+        inviteLink.SetNewId();
+
+        await organizationInviteLinkRepository.CreateAsync(inviteLink);
+
+        return inviteLink;
+    }
+
+    private async Task<bool> OrganizationHasInviteLinksAbilityAsync(Guid organizationId)
+    {
+        var ability = await applicationCacheService.GetOrganizationAbilityAsync(organizationId);
+        return ability is not null && ability.UseInviteLinks;
+    }
+
+    /// <summary>
+    /// Normalizes domains to lowercase and removes blank entries.
+    /// </summary>
+    private static List<string> SanitizeDomains(IEnumerable<string>? domains) =>
+        domains?
+            .Select(d => d?.Trim().ToLowerInvariant())
+            .Where(d => !string.IsNullOrEmpty(d))
+            .Cast<string>()
+            .ToList() ?? [];
+}

src/Core/AdminConsole/OrganizationFeatures/InviteLinks/CreateOrganizationInviteLinkRequest.cs

@@ -0,0 +1,13 @@
+namespace Bit.Core.AdminConsole.OrganizationFeatures.InviteLinks;
+
+public record CreateOrganizationInviteLinkRequest
+{
+    public required Guid OrganizationId { get; init; }
+    public required IEnumerable<string> AllowedDomains { get; init; }
+    public required string EncryptedInviteKey { get; init; }
+
+    /// <summary>
+    /// The organization key encrypted for the invite link. Currently unused; will be populated in a future stage.
+    /// </summary>
+    public string? EncryptedOrgKey { get; init; }
+}

src/Core/AdminConsole/OrganizationFeatures/InviteLinks/Errors.cs

@@ -0,0 +1,12 @@
+using Bit.Core.AdminConsole.Utilities.v2;
+
+namespace Bit.Core.AdminConsole.OrganizationFeatures.InviteLinks;
+
+public record InviteLinkAlreadyExists()
+    : ConflictError("An invite link already exists for this organization.");
+
+public record InviteLinkDomainsRequired()
+    : BadRequestError("At least one allowed domain is required.");
+
+public record InviteLinkNotAvailable()
+    : BadRequestError("Your organization's plan does not support invite links.");

src/Core/AdminConsole/OrganizationFeatures/InviteLinks/Interfaces/ICreateOrganizationInviteLinkCommand.cs

@@ -0,0 +1,14 @@
+using Bit.Core.AdminConsole.Entities;
+using Bit.Core.AdminConsole.Utilities.v2.Results;
+
+namespace Bit.Core.AdminConsole.OrganizationFeatures.InviteLinks.Interfaces;
+
+public interface ICreateOrganizationInviteLinkCommand
+{
+    /// <summary>
+    /// Creates a new invite link for the specified organization.
+    /// </summary>
+    /// <param name="request">The details for the invite link to create.</param>
+    /// <returns>The created <see cref="OrganizationInviteLink"/>, or an error if validation fails or a link already exists.</returns>
+    Task<CommandResult<OrganizationInviteLink>> CreateAsync(CreateOrganizationInviteLinkRequest request);
+}

src/Core/AdminConsole/Utilities/v2/Errors.cs

@@ -12,4 +12,5 @@ public abstract record Error(string Message);
 public abstract record NotFoundError(string Message) : Error(Message);
 
 public abstract record BadRequestError(string Message) : Error(Message);
+public abstract record ConflictError(string Message) : Error(Message);
 public abstract record InternalError(string Message) : Error(Message);

src/Core/OrganizationFeatures/OrganizationServiceCollectionExtensions.cs

@@ -6,6 +6,8 @@
 using Bit.Core.AdminConsole.OrganizationFeatures.Groups;
 using Bit.Core.AdminConsole.OrganizationFeatures.Groups.Interfaces;
 using Bit.Core.AdminConsole.OrganizationFeatures.Import;
+using Bit.Core.AdminConsole.OrganizationFeatures.InviteLinks;
+using Bit.Core.AdminConsole.OrganizationFeatures.InviteLinks.Interfaces;
 using Bit.Core.AdminConsole.OrganizationFeatures.OrganizationApiKeys;
 using Bit.Core.AdminConsole.OrganizationFeatures.OrganizationApiKeys.Interfaces;
 using Bit.Core.AdminConsole.OrganizationFeatures.OrganizationConnections;
@@ -45,6 +47,7 @@
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.DataProtection;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Logging;
 using AccountRecoveryV2 = Bit.Core.AdminConsole.OrganizationFeatures.AccountRecovery.v2;
 using V1_RevokeUsersCommand = Bit.Core.AdminConsole.OrganizationFeatures.OrganizationUsers.RevokeUser.v1;
@@ -64,6 +67,7 @@ public static void AddOrganizationServices(this IServiceCollection services, IGl
         services.AddOrganizationApiKeyCommandsQueries();
         services.AddOrganizationCollectionCommands();
         services.AddOrganizationGroupCommands();
+        services.AddOrganizationInviteLinkCommands();
         services.AddOrganizationDomainCommandsQueries();
         services.AddOrganizationSignUpCommands();
         services.AddOrganizationDeleteCommands();
@@ -187,6 +191,11 @@ private static void AddOrganizationGroupCommands(this IServiceCollection service
         services.AddScoped<IUpdateGroupCommand, UpdateGroupCommand>();
     }
 
+    private static void AddOrganizationInviteLinkCommands(this IServiceCollection services)
+    {
+        services.TryAddScoped<ICreateOrganizationInviteLinkCommand, CreateOrganizationInviteLinkCommand>();
+    }
+
     private static void AddOrganizationDomainCommandsQueries(this IServiceCollection services)
     {
         services.AddScoped<ICreateOrganizationDomainCommand, CreateOrganizationDomainCommand>();

src/Core/Utilities/ValidateSequenceAttribute.cs

@@ -0,0 +1,42 @@
+using System.ComponentModel.DataAnnotations;
+using System.Globalization;
+
+namespace Bit.Core.Utilities;
+
+/// <summary>
+/// Validates each element of a collection using <typeparamref name="TValidator"/>.
+/// The property must be <see cref="IEnumerable{T}"/> of a reference type (e.g. <c>IEnumerable&lt;string&gt;</c>).
+/// An empty collection passes validation; use <c>[MinLength(1)]</c> if an empty collection should be invalid.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Parameter)]
+public class ValidateSequenceAttribute<TValidator> : ValidationAttribute
+    where TValidator : ValidationAttribute, new()
+{
+    private const string _invalidItemsMessage = "The following items are not valid: {0}";
+
+    protected override ValidationResult? IsValid(object? value, ValidationContext validationContext)
+    {
+        if (value is null)
+        {
+            return ValidationResult.Success;
+        }
+
+        if (value is not IEnumerable<object> items)
+        {
+            throw new ArgumentException("ValidateSequenceAttribute can only be used with IEnumerable<T> properties.");
+        }
+
+        var validator = new TValidator();
+        var invalid = items.Where(item => !validator.IsValid(item)).ToList();
+
+        if (invalid.Count == 0)
+        {
+            return ValidationResult.Success;
+        }
+
+        var memberNames = new[] { validationContext.MemberName ?? validationContext.DisplayName };
+        var message = string.Format(CultureInfo.InvariantCulture, _invalidItemsMessage, string.Join(", ", invalid.Select(value => $"'{value}'")));
+
+        return new ValidationResult(message, memberNames!);
+    }
+}