@jcdubs/janus

v1.2.0

Published

8 days ago

Open source Serverless authentication: A Cedar-based authorisation engine for deterministic, deny-by-default access decisions through a CDK construct and SDK libraries.

0High
0Medium
0Low

jasonconway-williams

serverless authentication cdk sdk typescript aws open-source

Janus

Open source serverless authentication: A Cedar-based authorization engine for deterministic, deny-by-default access decisions through a CDK construct and SDK libraries.

Overview

Janus is a TypeScript library that provides fine-grained, policy-based authorization for AWS Lambda functions using Cedar. It enables you to define complex authorization rules and evaluate them efficiently within your serverless applications.

Janus is based on the pattern discussed in this blog post: Serverless: Granular Authorisation with Cedar — High control, minimal cost.

Key Features

🔐 Cedar Policy Engine - Leverage Amazon's Cedar policy language for authorization
⚡ Serverless Optimised - Designed for AWS Lambda with singleton caching
🎯 Type-Safe - Full TypeScript support with comprehensive type definitions
🔄 Fluent API - Intuitive method chaining for building authorization requests
🧪 Well Tested - Comprehensive test coverage with real-world examples
📦 Zero Config - Easy integration with minimal setup

Installation

Install the Package

npm install @jcdubs/janus

pnpm add @jcdubs/janus

yarn add @jcdubs/janus

Install Peer Dependencies

Janus requires the following peer dependencies to be installed in your project:

# For AWS Lambda PowerTools (logging)
npm install @aws-lambda-powertools/[email protected]

# For AWS CDK (if using CDK constructs)
npm install [email protected] [email protected]

With pnpm:

pnpm add @aws-lambda-powertools/[email protected]
pnpm add [email protected] [email protected]

With yarn:

yarn add @aws-lambda-powertools/[email protected]
yarn add [email protected] [email protected]

Note: The CDK dependencies (aws-cdk-lib and constructs) are only required if you're using Janus in a CDK application. For Lambda runtime usage only, you just need @aws-lambda-powertools/logger.

Quick Start

1. Define Your Cedar Policy

Create a policies.cedar file:

// Allow users to view their own orders
permit (
  principal,
  action == Action::"viewOrder",
  resource
) when {
  principal.id == resource.customerId
};

2. Define Your Cedar Schema

Create a schema.cedarschema file:

namespace OrderService {
  entity User = {
    id: String,
    roles: Set<Role>
  };
  
  entity Order = {
    customerId: String,
    status: String
  };
  
  entity Role;
  
  action viewOrder appliesTo {
    principal: User,
    resource: Order
  };
}

Implement the Auth Lambda

The following example demonstrates a simple AWS Lambda handler that uses the middleware to load Cedar authorization and then performs an authorization check inside the handler.

import middy from '@middy/core';
import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
import {
  loadCedarAuthorization,
  AuthorizationService,
  EntityBuilder,
  getUserName,
} from '@jcdubs/janus';

const authorizationConfig = {
  namespace: 'OrderService::',
  principleType: 'User',
  resourceType: 'Order',
  roleType: 'Role',
};

const handler = async (
  event: APIGatewayProxyEvent,
): Promise<APIGatewayProxyResult> => {
  // AuthorizationService is cached by the middleware, but retrieving it here is safe
  // and inexpensive (cached) and makes the intent explicit in the handler.
  const authService = await AuthorizationService.getService(authorizationConfig);

  const resourceId = event.pathParameters?.orderId ?? 'order-123';

  const isAuthorized = authService
    .setAction('viewOrder')
    .setResource(resourceId)
    .addEntity(
      new EntityBuilder(resourceId, authorizationConfig)
        .withStringAttr('customerId', getUserName())
        .build(),
    )
    .isAuthorized();

  return {
    statusCode: isAuthorized ? 200 : 403,
    body: JSON.stringify({ allowed: isAuthorized }),
  };
};

export const main = middy(handler).use(loadCedarAuthorization(authorizationConfig));

3. Use the Authorization Service

import { AuthorizationService, EntityBuilder } from '@jcdubs/janus';

// Define the authorization configuration and initialize the service (cached as a singleton)
const authorizationConfig = {
  namespace: 'OrderService::',
  principleType: 'User',
  resourceType: 'Order',
  roleType: 'Role'
};

const authService = await AuthorizationService.getService(authorizationConfig);

// Examples showing varied `EntityBuilder` usage patterns

// Minimal: build an entity with only UID
const isAuthorizedMinimal = authService
  .setAction('viewOrder')
  .setResource('order-123')
  .addEntity(new EntityBuilder('order-123', authorizationConfig).build())
  .isAuthorized();

// Typical: add a few simple attributes
const isAuthorizedTypical = authService
  .setAction('viewOrder')
  .setResource('order-123')
  .addEntity(
    new EntityBuilder('order-123', authorizationConfig)
      .withStringAttr('customerId', 'user-456')
      .withStringAttr('status', 'PENDING')
      .withNumberAttr('items', 3)
      .build()
  )
  .isAuthorized();

// Full: include sets, references, extension attrs, parents and tags
const isAuthorizedFull = authService
  .setAction('viewOrder')
  .setResource('order-123')
  .addEntity(
    new EntityBuilder('order-123', authorizationConfig)
      .withStringAttr('customerId', 'user-456')
      .withBooleanAttr('active', true)
      .withNumberAttr('items', 5)
      .withSetAttr('flags', ['flagA', 'flagB'])
      .withAttr('owner', 'u1', authorizationConfig.principleType)
      .withExtnAttr('ip', 'ipaddr', '192.168.1.10')
      .withParent('role-1', 'Role')
      .withTag('label', 'lbl1', 'Label')
      .build()
  )
  .isAuthorized();

logger.info('Create authorisation requests', isAuthorizedMinimal, isAuthorizedTypical, isAuthorizedFull);

API Reference

AuthorizationService

Static Methods

`getService(config, refresh?)`

Retrieves or creates a cached instance of the Authorization Service.

Parameters:

config: AuthorizationConfigType - Configuration object
- namespace: string - Cedar namespace (e.g., 'OrderService::')
- principleType: string - Principal entity type (e.g., 'User')
- resourceType: string - Resource entity type (e.g., 'Order')
- roleType: string - Role entity type (e.g., 'Role')
refresh?: boolean - Force reload policies and schemas (default: false)

Returns: Promise<AuthorizationService>

Instance Methods