Skip to main content

KeyCard for JavaScript

Pre-alpha

KeyCard is in pre-alpha. The API and policy format are still subject to breaking changes without notice. It is not yet recommended for production use.

JavaScript access-control library inspired by CASL.js, written in TypeScript with full type definitions included. Provides strongly-typed, composable authorization policies with compile-time safety for Actions and Subjects. Runs in the browser as well as server-side (Node.js and other JS runtimes).

New to KeyCard's concepts? Read the language-agnostic Guide first — Policy Definition, Rules, and the condition language are the same across every implementation.

Features​

  • Type-safe Actions & Subjects — branded types prevent typos and ensure type-safe refactoring
  • Composable — build complex policies from simple rules
  • Flexible conditions — comparison, pattern matching, and logical operators
  • Cross-language — PolicyDefinitions serialize to JSON for cross-platform use
  • Extensible — custom condition operators

Installation​

npm install @cptn-fizzbin/keycard

Quick start​

import { createAction, createSubject, PolicyBuilder, Policy } from '@cptn-fizzbin/keycard';
import type { InferActions, InferSubjects, KeycardConfig } from '@cptn-fizzbin/keycard';

// Define your action and subject types
const Actions = {
create: createAction("create"),
update: createAction("update"),
delete: createAction("delete"),
} as const;

const Subjects = {
article: createSubject<{ id: number; ownerId: number }>("article"),
} as const;

// InferActions/InferSubjects derive the union types PolicyBuilder
// and Policy expect, so you don't have to spell out
// `typeof Actions[keyof typeof Actions]` by hand.
type AppActions = InferActions<typeof Actions>;
type AppSubjects = InferSubjects<typeof Subjects>;

// Bundle the action/subject vocabulary into one KeycardConfig, built once
// and shared by every PolicyBuilder/Policy instead of kept in sync by hand
const config: KeycardConfig = {
actions: Actions,
subjects: Subjects,
};

// Build a policy scoped to one user
function createUserPolicy(user: { id: number }): Policy<AppActions, AppSubjects> {
return new PolicyBuilder<AppActions, AppSubjects>(config)
.allow(Actions.create, Subjects.article)
.allow(Actions.update, Subjects.article, { ownerId: user.id })
.build();
}

const policy = createUserPolicy({ id: 1 });

// Check by subject definition
if (policy.can(Actions.create, Subjects.article)) {
// Create article
}

// Check by subject instance
const article = Subjects.article.wrap({ id: 1, ownerId: 1 });
if (policy.can(Actions.update, article)) {
// Update article
}

// Require permission (throws if denied)
policy.require(Actions.delete, article); // Throws PolicyError if not allowed

Type safety​

KeyCard provides compile-time type safety:

  • Actions can only be created with createAction
  • Subjects must match their defined shape
  • Policy methods only accept valid Action/Subject combinations
  • Refactoring actions/subjects updates all policy rules

Continue to the API Reference, or see Examples for more complete walkthroughs.