Privileges

The IAM service, allowed privileges are demo, restricted, protected full and custom. When a new token is created, with a specified privilege, the token is scoped in the database level to that privilege. Any verification attempts with a privilege other then the one specified, will fail.

That means the IAM doesn't have any business knowledge, or an 'idea' what each level means to your client or app. Because of this design, and because every app has its own needs, the IAM gives you a flexible Core to ensure that the token it assigned to a user, will not escalate to a privilege its not created with, and vice versa.

This lets you structure, features, plans, RBAC, and more, to a specific user (or even plan), reliably.

You can control the privilege for each token in 3 processes:

• When creating a token
• Directly updating the field with updatePrivileges or the POST /api/manage/privilege-update endpoint.
• Using the privateActionManager to make additional verification before updating. The endpoint uses this function, instead of updatePrivileges

Updating Privileges

Using the library

To update a privilege directly, you call updatePrivileges. This function searches for hashed token in the database, the user id, and updates the privilege:

import { updatePrivileges } from '@riavzon/auth'

const userId = 1234
const newPriv = 'full'
const token = 'token' // can be hashed or raw.

const results = await updatePrivileges(userId, token, newPriv)

On success you get back an object with:

{
 ok: true,
 date: new Date().toISOString(),
 data: { msg: 'Privileges updated successfully' }
}

On error:

 ok: false,
 date: new Date().toISOString(),
 reason: 'the reason of the failure'

If an database error happens the reason would be 'Internal server error' if the token didn't found 'Token not found or unauthorized'.

Signature

export async function updatePrivileges(
    userId: number,
    rawToken: string,
    newPrivileges: 'demo' | 'restricted' | 'protected' | 'full' | 'custom',
): Promise<Results<{ msg: string }>>

Parameters

With the privateActionManager

    const updatePrivilegesResults = 
     await privateActionManager(userId, TokenId, publicIdentifier, tokenName, {
        action: 'privilege-update',
        newPrivileges: newPrivilege
     });

The privateActionManager returns the response of updatePrivileges directly. Learn more at the introduction page.

Using the route

Lets say you want to update a token privilege from demo to restricted in this example.

POST /api/manage/privilege-update body:

{
    "newPrivilege": "restricted",
    "tokenId": 2,
    "publicIdentifier": "pubkey",
    "name": "the token name"
}

On success you will get the following response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "ok": true,
  "date": "current date",
  "data": { "msg": "Privileges updated successfully" }
}

Aside from the standard errors that related to authentication, rate limits, and provided bad data,

The response you get is the same one the the library users get above:

HTTP/1.1 400
Content-Type: application/json; charset=utf-8

{
  "ok": false,
  "date": "current date",
  "reason": "reason from `privateActionManager`"
}

Rate Limits

The endpoint also enforce rate limits controlled under the following configuration options:

• rate_limiters.apiTokensLimiters.operationRateLimits.privilegeUpdate - The main limiter for the privilege update endpoint. The default allows 5 creations in a window of 10 minutes and will trigger a block for 30 minutes if this limit is met. Consecutive triggers in this period will block the client permanently.
• rate_limiters.apiTokensLimiters.generalUnionLimiter - A burstLimiter and a slowLimiter union limiter. Enforces no more than one request per second, and only 50 per minute. No Consecutive triggers in this limiter, triggering it again will result in a permanent ban. The limiter is restarted on successful updates.
  • burstLimiter - Will block the client for 15 minutes.
  • slowLimiter - Will block for 1 hour.

Configuration Reference

Rate limiters