[feature] Epic: Define automatic sessions for trusted clients

[marwannettour]

Summary

Introduce the product and domain foundation for automatic cloud session creation between clients that are already trusted by the current machine.

The goal is to let a user select one or more trusted clients and create a cloud session with them without manually sharing a session ID and password, while preserving ByteSync's existing trust model.

Context

The security analysis shows that ByteSync already has the key building blocks:

• persistent client identity based on RSA keys;
• local trusted public keys;
• silent trust checks when both sides already trust each other;
• encrypted session password and AES key exchange;
• mutual authentication through digital signatures.

This epic should define the first product-level contract for automatic sessions before UI and CLI surfaces are added.

Proposed scope

• Define the automatic trusted-session use case and terminology.
• Decide how a creator targets trusted clients by stable ClientId.
• Validate limits such as maximum remote clients per session.
• Define how automatic session creation interacts with existing cloud session creation.
• Define failure states when a selected client is missing, offline, not mutually trusted, revoked, or incompatible.
• Keep the initial scope limited to clients that were already manually trusted.

Out of scope

• Zero-touch enrollment of brand new machines.
• PKI, MDM, or enterprise trust roots.
• Replacing the existing manual session flow.
• Weak token-only passwordless authentication.

Acceptance criteria

• A product and domain design exists for creating a session from a list of trusted ClientId values.
• The design confirms that the current client is always a member of the created session.
• The design documents how the existing session password and AES key flow is preserved or adapted.
• The design documents failure behavior for non-trusted, partially trusted, offline, revoked, and incompatible clients.
• The implementation plan identifies the shared Common, Client, Functions, and ServerCommon changes needed for follow-up epics.
• Unit and integration test scenarios are listed for the automatic session happy path and main rejection paths.

Security position

Automatic session creation must only remove repeated manual input. It must not remove the cryptographic trust requirement. A client can be auto-invited only if the relevant trust and authorization checks pass.

[marwannettour]

Proposed implementation sequence:

1. [feature] Epic: Define automatic sessions for trusted clients #300 defines the product and domain contract for automatic sessions.
2. [feature] Epic: Add trusted-device grants for automatic joins #295 adds persistent trusted-device grants.
3. [feature] Epic: Add signed challenge flow for automatic joins #298 adds the signed challenge-response proof for automatic joins.
4. [feature] Epic: Add CLI command for trusted-client sessions #296 exposes the first operator workflow through CLI/headless usage.
5. [feature] Epic: Add Trusted Clients UI session start #297 exposes the same capability from the Trusted Clients UI.
6. [feature] Epic: Add governance and audit for automatic joins #299 completes the feature with governance, audit, revocation, expiration, and key-rotation handling.

MVP recommendation: ship #300, #295, #298, and a narrow slice of either #296 or #297 first, then harden with #299 before broader release.

[marwannettour]

Design draft added locally on branch feature/automatic-trusted-sessions-design in docs/automatic-trusted-sessions-design.md.

Child tickets created for the first implementation slice:

1. [feature] Define automatic session DTOs and failure reasons #303 - Define automatic session DTOs and failure reasons
2. [feature] Resolve trusted targets for automatic sessions #302 - Resolve trusted targets for automatic sessions
3. [feature] Add automatic session orchestration service #306 - Add automatic session orchestration service
4. [feature] Add automatic session invitations and prechecks #305 - Add automatic session invitations and prechecks
5. [test] Add automatic session contract tests #304 - Add automatic session contract tests
6. [test] Add automatic trusted session integration tests #301 - Add automatic trusted session integration tests

These children keep #300 focused on the product/domain contract while giving the implementation work a concrete starting backlog.