This package provides a TypeScript/JavaScript client for AWS Verified Permissions (AVP) that implements the Cedar Authorization Engine interface. For more information about the Cedar Authorization Engine, see authorization-for-expressjs.

The AVPAuthorizationEngine class provides an implementation of the Cedar AuthorizationEngine interface that integrates with Cedar framework integrations. This package allows you to perform authorization checks using either the IsAuthorized or IsAuthorizedWithToken AVP APIs.

npm install @verifiedpermissions/authorization-clients-js

import { AVPAuthorizationEngine } from '@verifiedpermissions/authorization-clients-js';

const engine = new AVPAuthorizationEngine({
    policyStoreId: 'your-policy-store-id',
    callType: 'isAuthorized'
});

The AVPAuthorizationEngine constructor accepts the following properties:

• policyStoreId (required): The ID of your Amazon Verified Permissions policy store
• callType (required): The type of authorization call to make. Can be one of:
  • 'isAuthorized': Direct entity-based authorization (you need to handle authentication and pass a correct principal entity)
  • 'accessToken': IsAuthorizedWithToken using access tokens (You can pass an access token as the principal entity that will be used to call IsAuthorizedWithToken)
  • 'identityToken': IsAuthorizedWithToken using identity tokens (You can pass an identity token as the principal entity that will be used to call IsAuthorizedWithToken)
• credentials (optional): AWS credentials or credential provider for the Amazon Verified Permissions client

When using callType: 'isAuthorized', the engine performs authorization checks by calling IsAuthorized:

const request = {
    principal: { type: 'User', id: 'user123' },
    action: { type: 'Action', id: 'view' },
    resource: { type: 'Document', id: 'doc123' },
    context: { /* additional context */ }
};

const entities = [/* Cedar entities */];

const result = await engine.isAuthorized(request, entities);

When using callType: 'accessToken' or 'identityToken', the engine performs authorization by calling IsAuthorizedWithToken:

const request = {
    principal: { type: 'Token', id: 'your-token' }, // Token goes in principal.id
    action: { type: 'Action', id: 'view' },
    resource: { type: 'Document', id: 'doc123' },
    context: { /* additional context */ }
};

const entities = [/* Cedar entities */];

const result = await engine.isAuthorized(request, entities);

Both APIs return a promise that resolves to an AuthorizationResult:

• Allow Result:

{
    type: 'allow',
    authorizerInfo: {
        principalUid: {
            type: string,
            id: string
        },
        determiningPolicies: string[]
    }
}

• Deny Result:

{
    type: 'deny'
}

• Error Result:

{
    type: 'error',
    message: string
}

The engine handles various error cases:

• Invalid policy store ID will throw an error during initialization
• Invalid call type will throw an error during initialization
• Authorization failures return a deny result
• Authorization errors (e.g., network issues, invalid tokens) return an error result

Check out express-petstore for a complete implementation of a protected API using this middleware.

See CONTRIBUTING for more information.

This project is licensed under the Apache-2.0 License.

Publishing to npm is done according to these links:

• https://docs.github.com/en/actions/use-cases-and-examples/publishing-packages/publishing-nodejs-packages
• https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release