Node.js SDK (@arkveil/node)

Install

npm install @arkveil/node arkveil

@arkveil/node requires the core arkveil package alongside it — arkveil is not bundled into @arkveil/node.

Usage

import { Arkveil } from "@arkveil/node";

const arkveil = new Arkveil({
  serviceUrl: "https://api.arkveil.com",
  apiKey: "your-api-key",
  getUserAttributes: (req) => ({ id: req.user?.id }),
});

app.post(
  "/api/admin",
  arkveil.permissionPoint("content-service.article-delete"),
  (req, res) => res.json({ message: "Protected content" }),
);

@arkveil/node exports ArkveilNodeClient as Arkveil — it extends the core Arkveil class, so every option and method described in the core SDK reference is available, plus the additions below.

API

arkveil.permissionPoint(code)

Returns an Express/Fastify-style middleware (req, res, next?).

• Resolves the permission request with buildPermissionRequest(code, req) (using your getUserAttributes/getContextAttributes extractors).
• Calls checkPermission.
• On grant, calls next().
• On denial, calls handleDenied(req, res, next).

Denial handling

handleDenied is overridden from the core client:

• If you pass a custom onDenied handler to the constructor, it's called with (req, res, reason?).
• Otherwise, the client auto-detects the framework:
  • Express/Fastify (when res.status is a function) — responds 403 with { error: "Access denied", reason: "..." } via res.status(403).json(...).
  • Raw Node http — writes the same JSON body via res.end(...).

const arkveil = new Arkveil({
  serviceUrl: "https://api.arkveil.com",
  apiKey: "your-api-key",
  onDenied: (req, res, reason) => {
    res.status(403).json({ error: "Forbidden", reason });
  },
});

Row-level data protection

@arkveil/node re-exports the core data-condition helpers and types verbatim (buildReadCondition, buildWriteChecks, normalizeDatasetCode, substituteIds, and related types/constants), so you can call them directly on the same client instance you use for permissionPoint. See Row-level data protection in the core reference.

Typed codes and attributes

@arkveil/node re-exports the core registry types (ArkveilCode, ArkveilCodeRegistry, ArkveilUser, ArkveilUserRegistry, ArkveilContext, ArkveilContextRegistry). Generate a typed augmentation file with the Arkveil CLI to get compile-time checked action codes and attribute shapes — see Typed codes & attributes.