Feature: search for people to share with, select several, and keep the permission checkboxes

[branch1337]

Description

With SHOW_USERNAMES_IN_UI enabled, opening the share modal loads every other account and renders one card per account under "Share with User". A small instance shows a few cards. An instance with hundreds of accounts runs the same path: one response with every username and email, and one card each inside the scroller. The search box only filters that already-loaded list. Finding one person means scrolling or filtering a directory that was fetched up front.

Sharing with the next person repeats the permission step. The grantor checks "Allow editing" or "Allow re-sharing", clicks a card, and that person appears under "Already Shared With". The click then clears both checkboxes. The next person needs the same boxes checked again. Ten recipients with the same permissions are ten searches through the directory and ten times re-checking the boxes.

The scroller itself is capped (max-h-[50vh] below the sm breakpoint, max-h-64 from sm up). The modal does not grow to the height of hundreds of cards. The cost is the full directory request, the hundreds of cards inside that cap, and the checkbox reset after every successful add.

Affected Version

v0.10.16-alpha

Requested Feature

The "Share with User" section is a search, a short result list, and a selected set.

The modal does not fetch or render the directory when it opens. The result area stays a one-line hint until the query has at least two characters. From two characters, the server returns at most 10 matches, ordered by username, matching the username or the email. The grantor's own account is absent, as it is today. Accounts that already have this recording, including the owner row, are left out of the results. A query that matches more than 10 people shows the first 10 and the grantor narrows the text.

Clicking a result selects that person. The click does not create a share and does not change the permission checkboxes. The selected people appear as removable chips under the search box. Clicking the result again, or the chip's remove control, deselects them. At most 25 people can be selected. Add is enabled when at least one person is selected. Add grants the current checkboxes to every selected person in one request, appends the new rows under "Already Shared With", clears the chips and the query, and leaves the checkboxes as they are.

The checkboxes start unchecked each time the modal opens. They stay at whatever the grantor set while the modal remains open, including after a successful Add and after a failed one. Closing the modal discards the query, the results, and the chips.

A name that already has a share is reported and skipped. The other selected people in that request still receive the share. The existing row's flags stay as they are.

The exact-username field used when SHOW_USERNAMES_IN_UI is false stays one username per Add. Public links, group-tag shares, and group-folder shares stay as they are. The "Already Shared With" list keeps its own capped scroller.

Proposed Implementation

search_users (src/api/shares.py:396-429) is the lookup the share modal already uses. Stop the branch that returns every user. A query shorter than 2 characters returns [] in both username modes. When usernames are visible and the query has at least 2 characters, match username or email with the existing literal contains_pattern, keep limit(10), and order by username:

query = request.args.get('q', '').strip()
if len(query) < 2:
    return jsonify([])

if SHOW_USERNAMES_IN_UI:
    pattern = contains_pattern(query)
    users = User.query.filter(
        User.id != current_user.id,
        db.or_(
            User.username.ilike(pattern, escape=LIKE_ESCAPE),
            User.email.ilike(pattern, escape=LIKE_ESCAPE),
        ),
    ).order_by(User.username).limit(10).all()
else:
    users = User.query.filter(
        User.id != current_user.id,
        User.username == query,
    ).all()

contains_pattern (src/utils/search.py:22-24) is the pattern the username branch already uses, so % and _ stay literal, which test_users_search_matches_underscore_literally covers. The hidden-username == branch stays. The JSON shape stays id, username, and email (email only when usernames are visible, src/api/shares.py:425-429).

share_recording_internal (src/api/shares.py:432-545) is the only creator of a manual internal share. When the JSON object contains user_ids, grant that list there and return. The user_id branch stays the one-recipient path, including 201, 409 already_shared, and the other current status codes. update_share (src/api/shares.py:368-381) stays the public-link settings update.

_MAX_SHARE_USERS = 25

def _grant_manual_internal_share(recording, target_user, can_edit, can_reshare):
    """Insert one manual share. Caller already checked access and the permission ceiling.
    Does not commit. Returns (share_or_none, status)."""
    if target_user.id == recording.user_id:
        return None, 'share_with_owner'
    if target_user.id == current_user.id:
        return None, 'share_with_self'
    existing = InternalShare.query.filter_by(
        recording_id=recording.id,
        shared_with_user_id=target_user.id,
    ).first()
    if existing:
        return None, 'already_shared'
    share = InternalShare(
        recording_id=recording.id,
        owner_id=current_user.id,
        shared_with_user_id=target_user.id,
        can_edit=can_edit,
        can_reshare=can_reshare,
    )
    db.session.add(share)
    state = SharedRecordingState.query.filter_by(
        recording_id=recording.id,
        user_id=target_user.id,
    ).first()
    if not state:
        db.session.add(SharedRecordingState(
            recording_id=recording.id,
            user_id=target_user.id,
            is_inbox=True,
            is_highlighted=False,
        ))
    else:
        state.is_inbox = True
    return share, 'shared'

At the start of the try in share_recording_internal, when isinstance(data, dict) and 'user_ids' in data:

if 'user_id' in data:
    return jsonify(api_error('user_id_or_user_ids')), 400
if not isinstance(data['user_ids'], list):
    return jsonify(api_error('user_ids_required')), 400

ids = []
seen = set()
for item in data['user_ids']:
    if isinstance(item, bool) or not isinstance(item, int):
        return jsonify(api_error('user_ids_required')), 400
    if item not in seen:
        seen.add(item)
        ids.append(item)
if not ids:
    return jsonify(api_error('user_ids_required')), 400
if len(ids) > _MAX_SHARE_USERS:
    return jsonify(api_error('user_ids_limit', max=_MAX_SHARE_USERS)), 400

recording = db.session.get(Recording, recording_id)
if not recording:
    return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user, require_reshare=True):
    return jsonify(api_error('recording_share_denied')), 403

can_edit = bool(data.get('can_edit', False))
can_reshare = bool(data.get('can_reshare', False))
is_valid, error_code = InternalShare.validate_reshare_permissions(
    recording, current_user, {'can_edit': can_edit, 'can_reshare': can_reshare}
)
if not is_valid:
    return jsonify(api_error(error_code)), 403

found = {
    user.id: user
    for user in User.query.filter(User.id.in_(ids)).all()
}
results = []
created = []
actor_permissions = InternalShare.get_user_max_permissions(recording, current_user)
for user_id in ids:
    target = found.get(user_id)
    if target is None:
        results.append({'user_id': user_id, 'status': 'not_found'})
        continue
    share, status = _grant_manual_internal_share(
        recording, target, can_edit, can_reshare
    )
    row = {'user_id': user_id, 'status': status}
    if status == 'shared':
        created.append((share, target))
    results.append(row)

db.session.commit()
for share, target in created:
    try:
        ShareAuditLog.log_share_created(
            recording_id=recording.id,
            actor_id=current_user.id,
            target_user_id=target.id,
            permissions={'can_edit': can_edit, 'can_reshare': can_reshare},
            actor_permissions=actor_permissions,
            notes=f"Shared by {'owner' if recording.user_id == current_user.id else 'delegated user'}",
            ip_address=request.remote_addr,
        )
        db.session.commit()
    except Exception as audit_error:
        current_app.logger.error(f"Failed to log share creation: {audit_error}")

return jsonify({'success': True, 'results': results}), 200

A body that is not a JSON object keeps the current handler. The user_id branch calls _grant_manual_internal_share for the insert and the inbox row, then returns the same status codes it returns today: missing id 400 user_id_required, unknown id 404 target_user_not_found, owner 400 share_with_owner, self 400 share_with_self, existing row 409 already_shared, ceiling failure 403, success 201 with share. On a shared batch row, include share.to_dict() after the commit. already_shared and not_found rows contain user_id and status only.

In static/js/modules/composables/sharing.js, delete the directory load. openUnifiedShareModal currently calls loadAllUsers and copies allUsers into the results (static/js/modules/composables/sharing.js:535-538). Remove that call, loadAllUsers (static/js/modules/composables/sharing.js:397-417), and the allUsers state. closeUnifiedShareModal (static/js/modules/composables/sharing.js:542-550) also clears the new selected list.

searchInternalShareUsers (static/js/modules/composables/sharing.js:419-438) is the handler on the visible-username input (templates/modals/unified-share-modal.html:111-112). Replace the local filter of allUsers with the debounced GET /api/users/search?q= that the hidden-username branch already uses (static/js/modules/composables/sharing.js:441-466). A query shorter than 2 characters clears the results and does not request. After the response, drop ids that are already in recordingInternalShares or in the selected chips. The local email match at static/js/modules/composables/sharing.js:433-436 goes away because the server query now matches email.

The card click at templates/modals/unified-share-modal.html:129-130 currently calls createInternalShare. Change it to toggle the user in a selected array. Render those users as chips between the result list and the permission block (templates/modals/unified-share-modal.html:168). Add a button, disabled while the selection is empty or a share is in flight, that posts:

await fetch(`/api/recordings/${internalShareRecording.value.id}/share-internal`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        user_ids: selectedUsers.map((user) => user.id),
        can_edit: internalSharePermissions.value.can_edit,
        can_reshare: internalSharePermissions.value.can_reshare
    })
});

On 200, reload the share list once and refresh the recording share count once, the same two calls createInternalShare makes at static/js/modules/composables/sharing.js:642-645. Toast with the count of shared rows. Drop chips that were shared or already_shared. Leave not_found, share_with_self, and share_with_owner selected and report them. Do not assign internalSharePermissions. Delete the reset at static/js/modules/composables/sharing.js:638-639 so createInternalShare, still used by shareWithUsername (static/js/modules/composables/sharing.js:605), also keeps the checkboxes. openUnifiedShareModal still sets both flags to false when the modal opens (static/js/modules/composables/sharing.js:473).

The result list keeps the capped grid classes at templates/modals/unified-share-modal.html:128. It renders only the current search page, at most 10 cards. Below two characters it shows a hint, not the "no users" empty state.

Add user_id_or_user_ids, user_ids_required, and user_ids_limit next to already_shared in server.apiError (static/locales/en.json:3129). Add the hint, the Add label, the selection cap, and the summary toast in sharing (static/locales/en.json:2420) and the same keys in de.json, es.json, fr.json, pt-BR.json, ru.json, and zh.json.

Update "Sharing a Recording with Another User" (docs/user-guide/sharing.md:30 and docs/user-guide/sharing.md:40): the modal asks for at least two characters, returns a short match list, and the grantor selects one or more people and presses Add. The permission checkboxes apply to that selection and stay checked until the modal is opened again. In docs/admin-guide/group-management.md:34 and docs/admin-guide/system-settings.md:147, say that visible usernames are searched and that the share modal does not load every account.

There is no browser test harness for this modal. The server tests live in tests/test_shares_authz.py, next to test_users_search_matches_underscore_literally and test_internal_share_owner_can_share_and_recipient_sees_it:

• test_users_search_short_query_returns_no_directory: with SHOW_USERNAMES_IN_UI true, q empty and q of one character return [] while other users exist.
• test_users_search_limits_and_orders_matches: 11 usernames that contain the same token, the response has 10 rows, ordered by username, and the caller is absent.
• test_users_search_matches_email: a query that occurs in the email and not in the username returns that user when usernames are visible.
• test_users_search_hidden_still_exact: with the flag false, a prefix returns [] and the full username returns that one user, with email null.
• test_share_internal_user_ids_batch: two ids, can_edit true, 200, two shared results, two manual rows with those flags, both recipients listed by shares-internal.
• test_share_internal_user_ids_already_shared_does_not_block_others: the existing row keeps its flags, the new id is shared.
• test_share_internal_user_ids_unknown_is_not_found: an id with no user is not_found and creates no row, and a real id in the same list is shared.
• test_share_internal_user_ids_dedupes: the same id twice creates one row.
• test_share_internal_user_ids_rejects_over_limit: 26 ids returns 400 user_ids_limit and creates no row.
• test_share_internal_user_ids_and_user_id_rejected: both fields returns 400 and creates no row.
• test_share_internal_user_ids_above_ceiling_denied: a grantor who lacks can_edit gets 403 and no rows.
• test_share_internal_user_ids_third_party_denied: a caller who cannot reshare gets 403 or 404 and no rows, matching test_internal_share_nonowner_without_reshare_denied.
• test_internal_share_owner_can_share_and_recipient_sees_it still returns 201 for a body that has only user_id.

Run them with python -m pytest tests/test_shares_authz.py -k "users_search or share_internal_user_ids or internal_share_owner_can_share" from the repository root.

Expected Behavior

• Opening the share modal shows the search box, the hint, and the permission checkboxes. It does not request GET /api/users/search?q=. No account cards are rendered yet.
• Typing one character still shows the hint and does not search. Typing two characters requests the search. The response has at most 10 objects, ordered by username, each with id, username, and email. A username or an email that contains the text matches. The caller is not in the list. People already on this recording are not shown. The grid scrolls inside the existing max-h-64 cap and never holds more than those 10 cards.
• Checking "Allow editing", selecting three results, and pressing Add creates three manual shares with can_edit true. The response is 200 with one result per id. Those three appear under "Already Shared With". The chips and the query clear. "Allow editing" stays checked. A second selection can be added with the same flags without checking the box again.
• Opening the modal again starts with both checkboxes unchecked (static/js/modules/composables/sharing.js:473).
• A selected id that already has a row is already_shared. That row's flags stay. The other ids in the request are still shared. unique_recording_share (src/models/sharing.py:87-91) still forbids a second row.
• A ceiling failure returns 403 with reshare_edit_not_permitted or reshare_reshare_not_permitted (src/models/sharing.py:165-170) and creates no row. A caller who cannot reshare gets the refusal the single-user POST already returns (src/api/shares.py:453-454).
• More than 25 ids, a non-list, a non-integer entry, an empty list, or user_ids together with user_id returns 400 and creates nothing.
• POST with only user_id still returns 201 and {success, share}, as in test_internal_share_owner_can_share_and_recipient_sees_it (tests/test_shares_authz.py:547-560). New shares still start in the recipient inbox (src/api/shares.py:506-517) and still write a ShareAuditLog create row.
• With usernames hidden, Add still sends one exact username through shareWithUsername. A short query still returns [] (src/api/shares.py:408-410). The "Already Shared With" scroller stays the block at templates/modals/unified-share-modal.html:219.

Root Cause Analysis

The visible picker is filled from the whole user table. openUnifiedShareModal calls loadAllUsers whenever showUsernamesInUI is true (static/js/modules/composables/sharing.js:535-538). That function requests GET /api/users/search?q= (static/js/modules/composables/sharing.js:402). search_users treats a query shorter than 2 characters, when usernames are visible, as "return every user except the caller" (src/api/shares.py:405-407). The template then loops internalShareSearchResults into a card grid (templates/modals/unified-share-modal.html:128-142). searchInternalShareUsers does not ask the server in this mode. It filters allUsers in the browser, including by email (static/js/modules/composables/sharing.js:422-437).

The same endpoint already has a bounded query, and the modal does not use it for this screen. When the query has at least 2 characters and usernames are visible, search_users applies ilike(contains_pattern(query)) and limit(10) (src/api/shares.py:412-417). That branch matches username only, has no order_by, and is reached from the hidden-username half of searchInternalShareUsers (static/js/modules/composables/sharing.js:441-451). The privacy input does not call that function. It calls shareWithUsername (templates/modals/unified-share-modal.html:150-155).

The checkbox reset is explicit. The card click calls createInternalShare (templates/modals/unified-share-modal.html:130). After a successful POST of one user_id (src/api/shares.py:441-446), that function sets internalSharePermissions back to { can_edit: false, can_reshare: false } (static/js/modules/composables/sharing.js:638-639). The checkboxes are bound to those two fields (templates/modals/unified-share-modal.html:172-185). The only other write is the open path, which clears them once per open (static/js/modules/composables/sharing.js:473). The user guide tells the grantor to check the boxes and then click the username, and says the share takes effect on that click (docs/user-guide/sharing.md:40). The admin guide describes visible usernames as the way colleagues are found (docs/admin-guide/group-management.md:34, docs/admin-guide/system-settings.md:147).

Additional Context

The permission checkboxes are the grant for the next Add. They are not an editor for people already listed under "Already Shared With". A batch result of already_shared does not change that row. Revoke stays the delete on DELETE /api/internal-shares/<id>.

This request does not paginate "Already Shared With". That list is a separate scroller with the same height cap (templates/modals/unified-share-modal.html:219). It does not change public link creation, and it does not change shares created by a group tag or a group folder. There is no /api/v1 operation for these session routes, so speakr-api-openapi.json stays as it is.

GET /api/users/search still requires login and still returns 403 when internal sharing is off (tests/test_shares_authz.py:454-466). Returning at most 10 matches replaces the unbounded directory response. Email is included only when SHOW_USERNAMES_IN_UI is true, which is the response the full directory already builds (src/api/shares.py:428).

[murtaza-nasir]

Thank you for the suggestion. The share window no longer loads every account. A search starts at two characters and lists up to 10 people whose username or email matches; email is searched only when usernames are shown. Several people can be selected and shared with at once, and the permission checkboxes keep their values until the window is closed. With usernames hidden, an exact username is still required. This will be included in the next release.

[branch1337]

Thank you for making this change! I think it’s a really useful improvement and makes sharing links much easier.