github.com/voedger/voedger@v0.0.0-20240520144910-273e84102129/design/verifiable-fields/readme-v1.md (about)

     1  ## Story
     2  - As a Heeus app developer I want to declare fields like Email and phone numbers that must be verified
     3  - As a Heeus app developer I want to verification be limited by tries amount or whatever to eliminate security holes
     4  
     5  ## Solution principles
     6  - verifiable fields are verified by 6-digit code got by crypto-safe randomize algorhythm
     7  - case with a link sent via email instead of code is bad because it could cause e.g. multiple payments after multiple opening the link
     8  - deny Token usage in a wrong WSID
     9  - limit rate of failured `q.sys.IssueVerifiedValueToken` (if a wrong code is provided)
    10    - match rates by the key (entity, ID, field)
    11  - additional authentication factor is the only way to secure the payment well enough
    12  
    13  ## Solution
    14  ```go
    15  WDoc<sys.VerifiedValueRateLimiter> {
    16  	failuresBatchStartMS int64
    17  	failuresBatchSize int64
    18  }
    19  // нужен для того, чтобы использовать существующий WDoc при создании нового токена с кодом
    20  View<sys.VerifiedValues> {
    21  	PK:    entity, ID, field
    22  	Value: WDoc<sys.VerifiedValueRateLimiter>.ID
    23  }
    24  ```
    25  
    26  ```go
    27  // не подходит, т.к. мы VerifiedValue используем в `c.sys.ResetPassword`, а там нет никакого ID
    28  // подходит, т.к. ResetPassword будет проверять только ID из токена, а частота уже проверена
    29  // ID должны проверяться по месту, т.к. c.sys.ResetPassword - это функция, там нет никакого ID -> на уровне движка ID не проверить
    30  ```
    31  
    32  <!-- ```mermaid
    33  sequenceDiagram
    34  	participant c as Client
    35  	participant b as Backend
    36  	participant h as HeeusAPI
    37  	participant s as AppStorage
    38  	c->>b: something that should return a verificationToken
    39  	activate b
    40  		b->>h: verifier.IssueVerificationToken(entity, ID, field) (token, code)
    41  		activate h
    42  			s->>h: read or create WDoc<sys.VerifiedValueRateLimiter>
    43  			h->>b: Code + VerifieficationToken with ID of WDoc<sys.VerifiedValueRateLimiter>
    44  		deactivate h
    45  		b->>c: token, code
    46  	deactivate b
    47  
    48  	c->>b: c.sys.ResetPassword(login, token, code)
    49  	activate b
    50  		b->>b: check ID
    51  		b->>h: verifier.GetVerifiedValue(token, code)
    52  		activate h
    53  			s->>h: WDoc<sys.VerifiedValueRateLimiter> by ID from the token
    54  			h->>h: check WSID
    55  			alt rate excess
    56  				h->>b: return error
    57  				b->>c: 429 too many requests
    58  			else
    59  				alt code is wrong
    60  					b->>s: update WDoc<sys.VerifiedValueRateLimiter>
    61  					h->>b: return error
    62  					b->>c: 403 unauthorized
    63  				else code is ok
    64  					h->>b: verified value
    65  					b->>b: reset password
    66  				end
    67  			end
    68  		deactivate h
    69  	deactivate b
    70  ``` -->
    71  
    72  ```mermaid
    73  sequenceDiagram
    74  	participant c as Client
    75  	participant b as Backend
    76  	participant h as HeeusAPI
    77  	participant s as AppStorage
    78  	c->>b: something that should return a verificationToken
    79  	activate b
    80  		b->>h: verifier.IssueVerificationToken(entity, ID, field) (token, code)
    81  		activate h
    82  			s->>h: read using view or create WDoc<sys.VerifiedValueRateLimiter>
    83  			h->>b: Code + VerificationToken with ID of WDoc<sys.VerifiedValueRateLimiter>
    84  		deactivate h
    85  		b->>c: token, code
    86  	deactivate b
    87  
    88  	c->>b: q.sys.IssueVerifiedValueToken
    89  	activate b
    90  		b->>h: verifier.IssueVerifiedValueToken(token, code) token
    91  		activate h
    92  			s->>h: read WDoc<sys.VerifiedValueRateLimiter> by ID from the token
    93  			h->>h: check WSID
    94  			alt rate excess
    95  				h->>b: return error
    96  				b->>c: 429 too many requests
    97  			else
    98  				alt code is wrong
    99  					h->>s: update WDoc<sys.VerifiedValueRateLimiter>
   100  					h->>b: return error
   101  					b->>c: 403 unauthorized
   102  				else code is ok
   103  					h->>b: return verifiedValueToken
   104  					b->>c: verifiedValueToken
   105  				end
   106  			end
   107  		deactivate h
   108  	deactivate b
   109  
   110  	c->>b: c.sys.ResetPassword
   111  	activate b
   112  		b->>b: check ID
   113  		b->>b: reset password
   114  		b->>c: 200ok
   115  	deactivate b
   116  ```
   117  
   118  
   119  <!-- ```mermaid
   120  sequenceDiagram
   121  	participant c as Client
   122  	participant b as Backend
   123  	participant s as AppStorage
   124  	c->>b: q.sys.IssueVerifiedValueToken
   125  	activate b
   126  		s->>b: read or create WDoc<sys.VerifiedValueRateLimiter> by key (entity, ID, field)
   127  		alt rate excess
   128  			b->>c: 429 too many requests
   129  		else
   130  			alt code is wrong
   131  				b->>s: update WDoc<sys.VerifiedValueRateLimiter>
   132  				b->>c: 403 unauthorized
   133  			else code is ok
   134  				b->>c: verifiedValueToken
   135  			end
   136  		end
   137  	deactivate b
   138  ``` -->