This page of the wiki is set up for you to understand the code behind the NASS contracts.

The core structure of the contracts is designed to be as much efficient, useful, and secure as possible. It contains general indexing values for the database as well as nested detailed informations for processing:

Note: Not all data under the CentralContracts type needs to be kept by the APIs, but all fields are useful for the NASS central system.

Defines what type of entity is being contracted:

export enum CONTRACTED {
  API = "API",        // The contract involves an API service
  USER = "USER"       // The contract involves a user
}

Defines who is initiating the contract:

export enum CONTRACTOR {
  API = "API",        // An API service is requesting the contract
  NASS = "NASS"       // The NASS system is issuing the contract
}

Defines the specific type of action the contract authorizes:

export enum CONTRACT_TYPE {
  TOKEN_RENEWAL = "TOKEN_RENEWAL",                    // API token refresh operations
  USER_AUTHENTIFICATION = "USER_AUTHENTIFICATION",   // User login/auth verification
  DATA_MANIPULATION = "DATA_MANIPULATION",           // User data read/write operations
  USER_MANAGEMENT = "USER_MANAGEMENT",               // User account administration
  SERVICE_MANAGEMENT = "SERVICE_MANAGEMENT",         // API service configuration
  BLACKLIST_MANAGEMENT = "BLACKLIST_MANAGEMENT",     // Security blacklist operations
  REQUESTS_MANAGEMENT = "REQUESTS_MANAGEMENT",       // Request logging and monitoring
  SERVICE_CONNECTION = "SERVICE_CONNECTION"          // Initial API service registration
}

Defines why a contract was terminated:

export enum CONTRACT_ENDING_REASON {
  COMPLETED = "COMPLETED",    // Contract fulfilled successfully
  CANCELED = "CANCELED",      // Contract canceled by contractor
  EXPIRED = "EXPIRED",        // Contract exceeded time limits
  FORCED = "FORCED"           // Contract terminated by system admin
}

• Every action requiring authorization generates a contract pair (ISSUER + RECEIVER)
• Each contract gets a unique id and links to its pair via associated_contract
• Contracts are immediately stored in the NASS database with active: true

• APIs must validate contracts before executing any authorized actions
• Validation checks include:
  • Contract is active: true
  • Current timestamp is within acceptable bounds of issued_at
  • contractor_id matches the requesting entity
  • api_key is valid (if applicable)

• When the authorized action is completed, the contract status is updated
• completed_at timestamp is recorded
• ending_reason is set to COMPLETED
• active is set to false

Contracts can be terminated early for several reasons:

• CANCELED: Contractor decides not to proceed
• EXPIRED: Contract took too long to fulfill
• FORCED: System administrator intervention

• Each contract contains cryptographic signatures to prevent tampering
• The associated_contract field ensures both parties have matching contract terms
• All contract modifications are logged with timestamps

When force_action: true, the contracted entity must execute the action:

• Used for critical security operations (token revocation, account suspension)
• Cannot be refused or canceled by the contracted entity
• Typically initiated by system administrators or security protocols

• The api_key field supports the constantly renewed API key system
• Contracts may reference old keys during transition periods
• Key validation occurs at both contract creation and execution time

For optimal performance, the following database indexes are recommended:

Primary indexes:

• id (unique, primary key)
• signature.contractor_id + status.active (contractor queries)
• signature.associated_contract (contract pair lookups)