# Authentication and Authorization with Platform v2

## Onboarding

### Invite a participant to the ecosystem

st=>start: Create Wallet
e=>end: Send Email Invitation
cond_is_org=>condition: Is Organization?
op_did=>operation: Register DID
op_cap=>operation: Assign Role 
- Individual
- Organization

st->cond_is_org
cond_is_org(no)->op_cap
cond_is_org(yes)->op_did
op_did->op_cap->e

## Authentication

Relies on a negotiation between the server and client, whereby the server issues a short-lived token that the client will need to submit in each subsequent request to be authenticated. The token is submitted as a header with a pre-defined scheme, e.g. `Bearer <token encoded as base64`

### Authentication: New Registration

sequenceDiagram
  autonumber

  participant User
  participant Client as Client SDK
  participant Server
  
  User->>+Client: Create new Wallet
  Client->>Client: Generate new DID
  Note over Client: DIDKey.generate()
  Client->>Client: Store DID in secure storage
  Client->>Client: Sign auth request
  Note over Client: DIDKey.sign()
  Client->>+Server: Send create wallet request
  Note over Client,Server: WalletService.CreateWallet()
  Server->>Server: Verify signature, extract did:key:alice-1
  Server->>Server: Create new peer DID as owner of the wallet
  Note right of Server: Generate BLS G1/G2 keys,<br/>Ed25519 and x25519.
  Server->>Server: Create new root capability
  Note right of Server: id = "urn:trinsic:wallet:alice"<br/>invoker = "did:peer:alice"<br />delegator = "did:peer:alice"
  Server->>Server: Create delegated capability
  Note right of Server: invoker = did:key:alice-1<br /> capability = urn:trinsic:wallet:alice
  Server-->>-Client: Create Wallet Response
  Note over Server,Client: Capability = urn:trinsic:wallet:alice<br/>Invoker = did:key:alice-1
  Client->>Client: Store Generated Key and Capability as Profile
  
  Client->>-User: Success

message {
    google.protobuf.Struct did_document = 1;
    string capability = 2; // reference to the wallet Id/capability
    string invoker = 3; // the specific key from the did document
}

---

### Authentication: Existing Registration

sequenceDiagram
  autonumber

  participant User
  participant Client as Client SDK
  participant Server
  
  User->>+Client: Authenticate to Wallet - SetProfile()
  Note over User,Client: WalletId = Alice<br/>
  Client->>Client: Retrieve Profile from secure storage
  Client->>Client: Sign auth request - Capability Ivocation
  Note over Client: LdProofs.createProof()
  Client-->-User: 
  User->>Client: Send endpoint request
  Client->Client: Append Auth header (Cap Inv)
  Client->+Server: Send request
  Note over Client,Server: AuthService.AcquireToken()
  Server->>Server: Check if DID has capability<br />for requested WalletId
  Note over Server: "Authorizations" Collection in CosmosDB
  Server-->>-User: Endpoint Response

## API Calls

- Attach auth token derived from profile.bin
- Capability invocation document per channel

- Added as metadata to the call
- pack, if secure endpoint
- send