did-auth-use-cases

Last updated: 2025-01-21 01:10:35.602290 File source: link on GitLab

ASI node design / DID:Auth use-cases

Intro

We are working toward four use-cases identified for pursuing pilots and then design of ASI node authentication layer, for which we aim to use NuActor system and OCaps system featuring . Each use case is described and will be implemented / piloted in a separate sub-folder. For fostering collaboration between ASI node design component owners, we will do it via git development flow as per NuNet Contribution guidelines.

• The original google sheet which is the source of these descriptions can be found here.

• Each use case description consists of scenario description, functional requirements and sequence diagrams;

• All auth use-cases and pilots must consider non-functional requirements that pertain to all auth layer functionality that we aim to propose/develop via pilots of these use-cases; non-functional requirements follow.

Non Functional requirements

These requirements shall be built into the test-suite of the api-node integration for running as regression test stage within the scope of NuNet's test-suite matrix.

Performance

1. Optimize Response Time for API Services. As a user of the API, I want the system to respond quickly to my requests so that I experience minimal delays when performing operations (e.g., authentication, hosting deployment, compute job submission).

   1. API response time for authentication and resource requests must be less than 200? milliseconds for 95% of requests under normal load.

   2. Compute job submissions must not exceed 500? milliseconds, even under peak loads.

   3. Latency for DID Document resolution must not exceed 150? milliseconds.

2. Ensure High Throughput for API Requests: As a system admin, I want the API to handle a large number of concurrent requests so that it can support multiple users simultaneously without performance degradation.

   1. The API must support 1,000? concurrent authentication requests per second under normal conditions.

   2. The system must process at least 500? compute job submissions per second during peak usage.

   3. Hosting Service must handle 200? concurrent file uploads without significant performance degradation.

3. Deliver Notifications in Near Real-Time: As a user, I want to receive notifications for long-running operations (e.g., compute jobs, hosting updates) quickly so that I’m updated about the status of my tasks.

   1. Notifications for job completions must be delivered within 2 seconds of completion.

   2. Error notifications for failed operations must be sent to the user within 1 second of the failure.

Security

1. Enforce DID Auth for API requests: As a user, I want the API to enforce DID Auth for all operations so that unauthorized users cannot access my resources.

   1. Every API call must involve a cryptographic challenge-response mechanism using DID Auth.

   2. Only requests signed with a valid private key corresponding to the DID’s public key must be processed.

   3. Requests without valid DID Documents or signatures must be rejected with an HTTP 401 Unauthorized error.

2. Encrypt all communications: As a system admin, I want all data exchanged with the API to be encrypted so that sensitive information is protected from unauthorized access.

   1. All communications between clients and the API must use TLS 1.3 or higher.

   2. Sensitive data such as compute job details, payment transactions, and hosted files must be encrypted at rest using AES-256 encryption.

   3. The system must reject requests that are not made over HTTPS.

3. Implement RBAC: As a developer, I want RBAC implemented in the API so that users can only access resources they are authorized for.

   1. Users must only have access to resources associated with their DID.

   2. Admin roles must have elevated permissions to access system-level resources (e.g., logs, usage metrics).

   3. Unauthorized access attempts must return an HTTP 403 Forbidden error.

4. Prevent reply attacks: As a user, I want the API to ensure that cryptographic challenges cannot be reused so that my identity is protected from replay attacks.

   1. All cryptographic challenges must include a unique nonce or timestamp.

   2. The API must reject requests with expired or duplicate challenges and respond with an HTTP 401 Unauthorized error.

   3. Challenges must expire after 5 minutes from the time of issuance.

Scalability

1. Support horizontal scaling: As a system admin, I want the API to scale horizontally so that it can handle increased workloads by adding more service instances.

   1. Each microservice (e.g., Hosting Service, Compute Service) must support horizontal scaling by deploying additional instances dynamically.

   2. The system must handle sudden spikes in traffic without downtime, with a maximum latency increase of 10% during scaling events.

2. Ensure Availability: As a global user, I want the API to be available in multiple regions so that I can access services with low latency.

   1. API endpoints must be deployed in at least 3 global regions (e.g., North America, Europe, Asia).

   2. Latency for requests from any region must not exceed 300 milliseconds.

   3. The system must automatically route requests to the nearest region.

3. Implement Fault Tolerance: As a system admin, I want the API to remain operational even if individual services fail so that the system can continue providing core functionality.

   1. If an individual microservice (e.g., DID Resolver) fails, fallback mechanisms (e.g., secondary services) must ensure continued operation.

   2. Compute jobs and hosted content must be recoverable within 5 minutes after a failure.

   3. The system must retry failed requests to downstream services up to 3 times before returning an error.

Usability

1. Provide clear API documentation: As a developer, I want the API to include comprehensive documentation so that I can easily integrate it into my applications.

   1. The API must include OpenAPI (Swagger) documentation with detailed descriptions of endpoints, request/response formats, and error codes.

   2. Example requests and responses must be provided for each endpoint.

   3. Documentation must be accessible via a public developer portal.

2. Return Actionable Error Messages: As a user, I want the API to return clear error messages so that I can troubleshoot issues easily.

   1. Errors must include meaningful messages (e.g., "Invalid DID signature", "Rate limit exceeded").

   2. Errors must include an HTTP status code and contextual information (e.g., the DID involved, operation attempted).

   3. 4xx errors must provide guidance on how to resolve the issue.

3. Support Wallet Integration: As a user, I want the API to integrate with DID-compatible wallets so that I can easily sign authentication challenges.

   1. The API must support popular wallets such as MetaMask, uPort, and Trinsic for DID authentication.

   2. The cryptographic challenge must be presented in a wallet-compatible format (e.g., JSON-LD, JWT).

   3. Users must be notified if their wallet is incompatible with the API.

4. Optimize for Low Bandwidth Devices: As a mobile or IoT user, I want the API to minimize bandwidth usage so that I can interact with it efficiently on limited networks.

   1. API requests and responses must be lightweight, using optimized formats such as JSON or binary protocols where applicable.

   2. Large data transfers (e.g., file uploads, compute results) must be chunked to avoid timeouts or bandwidth overuse.

   3. The API must support pagination for large datasets.