@lexardevelopment/cis-app-runtime

Client runtime for apps integrating with the Central Identity Service.

Provides four pieces:

• CisClient — authenticated HTTP wrapper around the CIS API
• PermissionCache — Redis-backed cache with degraded-mode fallback (Section 7.3)
• UserContext — declarative permission helpers (Section 7.4)
• WebhookHandler — signature-verified event dispatch with dedup

Install

The package is published to the public npm registry. No token or .npmrc is required — the source repo stays private; only the compiled dist is published.

npm install @lexardevelopment/cis-app-runtime ioredis

ioredis is an optional peer dep — only needed if you wire PermissionCache.

Usage

import Redis from "ioredis";
import {
  CisClient,
  PermissionCache,
  UserContext,
  WebhookHandler,
} from "@lexardevelopment/cis-app-runtime";

const cis = new CisClient({
  baseUrl: process.env.CIS_URL!,           // e.g. https://cis.example.com/api
  appId: "hub",
  getAccessToken: async () => fetchM2MToken(),
});

const redis = new Redis(process.env.REDIS_URL!);
const cache = new PermissionCache({ cis, redis });

// Session middleware
const payload = await cache.get(personId);
const ctx = new UserContext(payload);
if (!ctx.hasRole("editor")) return forbid();

// Webhook route
const handler = new WebhookHandler({
  webhookSecret: process.env.CIS_WEBHOOK_SECRET!,
  on: {
    "permission.changed":         (e) => cache.invalidate(e.personId),
    "person.archived":            (e) => cache.invalidate(e.personId),
    "person.merged":              (e) => cache.invalidateMany([e.fromPersonId, e.toPersonId]),
    "office.membership.changed":  (e) => e.personId ? cache.invalidate(e.personId) : undefined,
  },
});

See the design doc Section 7 for the full integration story and the Hub migration guide for a worked example.

Versioning

This package follows semver. Breaking changes to types or runtime behavior bump the minor version while we're pre-1.0; consumers should pin with ^0.x and review the CHANGELOG before upgrading.