did-auth-use-scenarios
Last updated: 2025-01-22 01:11:28.463324 File source: link on GitLab
DID:Auth use-scenarios
Logistics
In order to authentication layer for ASI Node design we aim to use NuActor system and OCaps system featuring decentralized authentication mechanism. We do this via developing pilots for identified use-scenarios. Each scenario is described and will be implemented / piloted in a separate sub-folder of this directory. 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.
Concepts
The main challenge of DID Auth layer is inherited from the same aspect that challenges the Web3 industry in general -- which is how to integrate 'Web2' based (centralized) authentication mechanisms to 'Web3' based (de-centralized authentication) mechanisms. It makes sense to frame this challenge as integration of concepts rather than 'gradual transitioning from Web2 to Web3 models' as components from both are needed.
The relation between these concepts can be best characterized in terms of dealing with security / access / authentication perimeters in the overall security architecture of systems and the role of these perimeters. Both models are well established computer security models.
In 'centralized' authentication systems, users are authenticated on the perimeter and get access to all resources within the system as defined in centralized access-control lists (ASLs) maintained at the point of the perimeter. ACL based authentication model requires a single point of access to the system (hence centralized);
'De-centralized' authentication systems by definition do not require single point of access to the system. Which means that each user of a system authenticates themselves to each component of the system directly -- sending, receiving and verifying object capability tokens directly. This is being achieved with Object Capabilities security model (OCaps), which, among many other things, fuses direct object reference with the authorization/capability of a user to use that object, where capability tokens are checked and verified in end-to-end manner at each object/component level.
A way to relate these two models, which we are proposing for the DID Auth layer of ASI node is to apply object oriented programming paradigm to the system integration, where each component of the system is defined as an object (actor) that manages its own access and capabilities via OCaps model in the context of interaction with other components/objects/actors, but is able to manage its internal resources based on whatever model it chooses internally. OCaps security model, however, enables secure computing at most granular level possible, down to drivers, hardware resources of files in file systems (see e.g. Wikipedia article with references).
NuNet orchestration layer leverages Actor model of computation and OCaps model via the NuActor system, which implements User Controlled Access Network (UCAN) standard of OCaps based authorization.
NuActor is a framework designed for secure actor oriented programming in decentralized systems. The framework utilizes zero trust interactions, whereby every message is authenticated individually at the point of interaction. The system supports fine-grained capabilities, anchored in decentralized identifiers (see DID) and effected with user controlled authorization network
UCANs are JWTs that contain special keys. At a high level, User Controlled Authorization Network (UCANs) are an authorization scheme ("what you can do") where users are fully in control. UCANs use DIDs ("Decentralized Identifiers") to identify users and services ("who you are"). No all-powerful authorization server or server of any kind is required for UCANs. Instead, everything a user can do is captured directly in a key or token, which can be sent to anyone who knows how to interpret the UCAN format. Because UCANs are self-contained, they are easy to consume permissionlessly, and they work well offline and in distributed systems.
With NuActor/UCANs we can do any level of authentication between peers/actors as informed by integration requirements and business needs, including Server -> Server, Client -> Server, Server -> Client, etc. (which actually dissolves the whole distinction between Server and Client where any peer can act in both roles in different scenarios).
Non Functional requirements
These requirements shall be built into the test-suite of the api-node integration for running as performance test stage within the scope of NuNet's test-suite matrix.
Performance
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).
API response time for authentication and resource requests must be less than 200? milliseconds for 95% of requests under normal load.
Compute job submissions must not exceed 500? milliseconds, even under peak loads.
Latency for DID Document resolution must not exceed 150? milliseconds.
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.
The API must support 1,000? concurrent authentication requests per second under normal conditions.
The system must process at least 500? compute job submissions per second during peak usage.
Hosting Service must handle 200? concurrent file uploads without significant performance degradation.
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.
Notifications for job completions must be delivered within 2 seconds of completion.
Error notifications for failed operations must be sent to the user within 1 second of the failure.
Security
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.
Every API call must involve a cryptographic challenge-response mechanism using DID Auth.
Only requests signed with a valid private key corresponding to the DID’s public key must be processed.
Requests without valid DID Documents or signatures must be rejected with an HTTP 401 Unauthorized error.
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.
All communications between clients and the API must use TLS 1.3 or higher.
Sensitive data such as compute job details, payment transactions, and hosted files must be encrypted at rest using AES-256 encryption.
The system must reject requests that are not made over HTTPS.
Implement RBAC: As a developer, I want RBAC implemented in the API so that users can only access resources they are authorized for.
Users must only have access to resources associated with their DID.
Admin roles must have elevated permissions to access system-level resources (e.g., logs, usage metrics).
Unauthorized access attempts must return an HTTP 403 Forbidden error.
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.
All cryptographic challenges must include a unique nonce or timestamp.
The API must reject requests with expired or duplicate challenges and respond with an HTTP 401 Unauthorized error.
Challenges must expire after 5 minutes from the time of issuance.
Scalability
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.
Each microservice (e.g., Hosting Service, Compute Service) must support horizontal scaling by deploying additional instances dynamically.
The system must handle sudden spikes in traffic without downtime, with a maximum latency increase of 10% during scaling events.
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.
API endpoints must be deployed in at least 3 global regions (e.g., North America, Europe, Asia).
Latency for requests from any region must not exceed 300 milliseconds.
The system must automatically route requests to the nearest region.
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.
If an individual microservice (e.g., DID Resolver) fails, fallback mechanisms (e.g., secondary services) must ensure continued operation.
Compute jobs and hosted content must be recoverable within 5 minutes after a failure.
The system must retry failed requests to downstream services up to 3 times before returning an error.
Usability
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.
The API must include OpenAPI (Swagger) documentation with detailed descriptions of endpoints, request/response formats, and error codes.
Example requests and responses must be provided for each endpoint.
Documentation must be accessible via a public developer portal.
Return Actionable Error Messages: As a user, I want the API to return clear error messages so that I can troubleshoot issues easily.
Errors must include meaningful messages (e.g., "Invalid DID signature", "Rate limit exceeded").
Errors must include an HTTP status code and contextual information (e.g., the DID involved, operation attempted).
4xx errors must provide guidance on how to resolve the issue.
Support Wallet Integration: As a user, I want the API to integrate with DID-compatible wallets so that I can easily sign authentication challenges.
The API must support popular wallets such as MetaMask, uPort, and Trinsic for DID authentication.
The cryptographic challenge must be presented in a wallet-compatible format (e.g., JSON-LD, JWT).
Users must be notified if their wallet is incompatible with the API.
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.
API requests and responses must be lightweight, using optimized formats such as JSON or binary protocols where applicable.
Large data transfers (e.g., file uploads, compute results) must be chunked to avoid timeouts or bandwidth overuse.
The API must support pagination for large datasets.
Last updated