KeyCard for Java
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.
Cross-language access-control library inspired by CASL.js. Provides type-safe, composable authorization policies for the JVM.
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 — generics ensure only valid actions and subjects are used
- Composable — build complex policies from simple rules using a fluent API
- Flexible conditions — comparison, pattern matching, and logical operators
- Cross-platform —
PolicyDefinitions serialize to JSON for cross-language use - Zero runtime overhead — type safety enforced at compile time via Java generics
Installation
Add to your pom.xml:
<dependency>
<groupId>com.cptnfizzbin</groupId>
<artifactId>keycard</artifactId>
<version>0.0.4</version>
</dependency>
Or with Gradle:
implementation 'com.cptnfizzbin:keycard:0.0.4'
Quick start
import com.cptnfizzbin.keycard.KeycardConfig;
import com.cptnfizzbin.keycard.action.Action;
import com.cptnfizzbin.keycard.subject.Subject;
import com.cptnfizzbin.keycard.builder.PolicyBuilder;
import com.cptnfizzbin.keycard.policy.Policy;
import com.cptnfizzbin.keycard.errors.PolicyException;
import java.util.List;
import java.util.Map;
class Article {
public final int id;
public final int ownerId;
public Article(int id, int ownerId) {
this.id = id;
this.ownerId = ownerId;
}
}
public class Main {
public static void main(String[] args) {
// Define your actions
Action create = new Action("create");
Action update = new Action("update");
Action delete = new Action("delete");
// Define your subjects
Subject<Article> article = new Subject<>("article");
// Bundle the action/subject vocabulary into one KeycardConfig, built
// once and shared by every PolicyBuilder/Policy instead of kept in
// sync by hand
KeycardConfig config = KeycardConfig.builder()
.actions(List.of(create, update, delete))
.subjects(List.of(article))
.build();
// Build a policy scoped to one user
int userId = 1;
Policy policy = new PolicyBuilder(config)
.allow(create, article)
.allow(update, article, Map.of("ownerId", userId))
.build();
// Check by subject type (no instance)
if (policy.can(create, article)) {
System.out.println("Can create articles");
}
// Check by subject instance
Article data = new Article(1, userId);
Subject<Article> ref = article.wrap(data);
if (policy.can(update, ref)) {
System.out.println("Can update own article");
}
// Require permission (throws if denied)
try {
policy.require(delete, ref);
} catch (PolicyException e) {
System.out.println("Access denied: " + e.getMessage());
}
}
}
Type safety
Java's generic type system enforces compile-time verification:
Action create = new Action("create");
Subject<Article> article = new Subject<>("article");
policy.
can(create, article); // OK
policy.
can("create",article); // compiler error: action must be an Action
policy.
can(create, "article"); // compiler error: subject must be a Subject<?>
Beyond the basics
Conditions— a type-safe condition builder using method references (Conditions.eq(Article::getOwnerId, 1)) instead of hand-writtenMap.of(...)literals.SubjectFieldMapper— resolve a condition field through an explicit getter instead of reflection, for a renamed or computed field.KeycardConfig— one object bundling actions/subjects/operators/field mappers, accepted by bothPolicyBuilderandPolicy.
See the API Reference for all three, or Examples for more complete walkthroughs.