SDK Overview

A lightweight, fail-closed client SDK for the Arkveil ABAC platform, with packages for core, Node.js, and NestJS.

What is the Arkveil SDK

Arkveil is an attribute-based access control (ABAC) platform. The arkveil-js SDK is a thin client that calls the Arkveil service to:

Decide if an action is allowed — checkPermission
Fetch SQL enforcement artifacts for row-level data protection — buildReadCondition and buildWriteChecks

The service you talk to can be Arkveil Cloud (https://api.arkveil.com) or a self-hosted arkveil-runtime sidecar — both expose the same contract behind an opaque base URL. The SDK never receives your policies, only rendered SQL and grant/deny decisions.

Packages

Package	Description
`arkveil`	Runtime-agnostic core SDK. Zero runtime dependencies.
`@arkveil/node`	Node.js SDK — permission middleware for Express, Fastify, and other HTTP frameworks.
`@arkveil/nest`	NestJS SDK — declarative ABAC permission checks via decorators and guards.

@arkveil/node and @arkveil/nest both build on top of the core arkveil package, so you'll always need it installed alongside the platform package you choose.

Install

# Core (runtime-agnostic)
npm install arkveil

# Node.js (Express, Fastify, etc.)
npm install @arkveil/node arkveil

# NestJS
npm install @arkveil/nest

Quick start

import { Arkveil } from "arkveil";

const arkveil = new Arkveil({
  serviceUrl: "https://api.arkveil.com",
  apiKey: "your-api-key",
});

const result = await arkveil.checkPermission({
  actionCode: "content-service.article-delete",
  user: { id: "user-123", role: "admin" },
  context: { region: "EU" },
});

if (result.granted) {
  // allow
} else {
  // deny
}

The apiKey is a workspace API key, sent as an x-api-key header. Mint one with the Arkveil CLI (arkveil keys create).

Design principles

Fail-closed. checkPermission never throws — network errors, timeouts, and non-OK responses are logged and resolved to { granted: false }. Row-level helpers degrade to the most restrictive condition on failure. The only exception is a malformed dataset code, which throws immediately as a configuration error rather than a runtime condition.
Typed by generation, not by hand. Action codes and user/context attribute shapes are modeled as pluggable generic parameters and global type registries. The arkveil CLI generates a TypeScript file that augments these registries for your workspace — see Typed codes & attributes.
Retried, bounded requests. Requests retry on 429 and 5xx responses and network failures with exponential backoff and jitter. 4xx errors (other than 429) are not retried.