NodePerm - SpiceDB SDK

A lightweight TypeScript SDK for interacting with SpiceDB, a Zanzibar-inspired permissions database.

[!WARNING] Status: Unstable. This project is currently in early development. Use at your own risk in production environments.

Installation

bun add @soramux/node-perm-sdk

Configuration

The library uses environment variables for default configuration:

• TRIEOH_AUTHZED_TOKEN: The default Bearer token for authentication.
• TRIEOH_AUTHZED_ENVIRONMENTS: A JSON array of environment configurations.

Example .env:

TRIEOH_AUTHZED_TOKEN=your-secret-token
TRIEOH_AUTHZED_ENVIRONMENTS='[{"name": "local", "url": "http://localhost:50051"}, {"name": "prod", "url": "https://spicedb.prod.com", "token": "prod-specific-token"}]'

Usage

1. Initialize the Client

You can initialize the client using a configured environment name or a direct configuration object.

import { spicedb } from "@trieoh/node-perm";

// Using environment name
const client = spicedb.permission("local");

// Using direct configuration
const customClient = spicedb.permission({
  url: "http://localhost:50051",
  token: "custom-token"
});

2. Permission Builder

The permission() builder is immutable and enforces mandatory fields (subject, resource, permission) at compile time.

import { permission } from '@soramux/node-perm-sdk';

const basePermission = permission()
  .subject("user", "sora");

// The original basePermission remains unchanged
const checkRead = basePermission
  .resource("document", "doc1")
  .permission("read");

const checkWrite = basePermission
  .resource("document", "doc1")
  .permission("write");

// build() is only available after subject, resource, and permission are set
const requestItem = checkRead.build();

3. Permission Checks

Single Check

const result = await client.check({
  resource: { objectType: "document", objectId: "doc1" },
  permission: "read",
  subject: { object: { objectType: "user", objectId: "sora" } }
});

console.log(result.data.permissionship);

Bulk Check

import { permission, spicedb } from "@soramux/node-perm-sdk";

const client = spicedb.permission("local");

const check1 = permission().subject("user", "sora").resource("doc", "1").permission("read").build();
const check2 = permission().subject("user", "sora").resource("doc", "2").permission("write").build();

const response = await client.checkBulk({
  items: [check1, check2]
});

// Use formatBulkResponse for a cleaner result
const results = client.formatBulkResponse(response.data);
results.forEach(r => {
  console.log(`${r.permission} on ${r.resource.objectId}: ${r.result}`);
});

4. Custom Token per Request

Every service call accepts an optional token override:

const result = await client.check(request, { token: "temp-session-token" });

Advanced Type Validation

The builder uses ValidIdent<T> to ensure identifiers (types, permissions, relations) at compile time. This mechanism is currently generic and experimental, and does not yet fully enforce SpiceDB naming conventions.

// This will cause a TypeScript error:
permission().permission("invalid-permission-name"); // contains '-'

Services

• spicedb.schema(config): Manage SpiceDB schema (read/write).
• spicedb.relationship(config): Manage relationships (create, update, delete, readStream).
• spicedb.permission(config): Perform permission checks (check, checkBulk).