@stratum-hq/core

@stratum-hq/core is the shared foundation for all Stratum packages. It exports TypeScript types, Zod validation schemas, error classes, utility functions, and constants. Every other Stratum package depends on it.

Installation

npm install @stratum-hq/core

You typically install this as a dependency of @stratum-hq/lib or @stratum-hq/sdk rather than directly.

Types

TenantNode

The complete tenant record as stored in the database:

interface TenantNode {
  id: string;                          // UUID
  parent_id: string | null;            // UUID of parent tenant
  ancestry_path: string;               // "/uuid1/uuid2"
  depth: number;                       // 0 = root
  name: string;                        // 1-255 chars
  slug: string;                        // ^[a-z][a-z0-9_]{0,62}$
  config: Record<string, unknown>;
  metadata: Record<string, unknown>;
  isolation_strategy: IsolationStrategy;
  region_id: string | null;
  status: TenantStatus;
  deleted_at: string | null;
  created_at: string;
  updated_at: string;
}

TenantContext

Resolved at runtime – includes effective config and permissions for a tenant:

interface TenantContext {
  tenant_id: string;
  ancestry_path: string;
  depth: number;
  resolved_config: Record<string, ResolvedConfigEntry>;
  resolved_permissions: Record<string, ResolvedPermission>;
  isolation_strategy: IsolationStrategy;
}

ResolvedConfigEntry

interface ResolvedConfigEntry {
  key: string;
  value: unknown;
  source_tenant_id: string;
  inherited: boolean;
  locked: boolean;
}

ResolvedPermission

interface ResolvedPermission {
  key: string;
  value: unknown;
  mode: string;                // LOCKED | INHERITED | DELEGATED
  source_tenant_id: string;
  locked: boolean;
  delegated: boolean;
}

Input Types

interface CreateTenantInput {
  parent_id?: string | null;
  name: string;
  slug: string;
  config?: Record<string, unknown>;
  metadata?: Record<string, unknown>;
  isolation_strategy?: IsolationStrategy;
}

interface SetConfigInput {
  value: unknown;
  locked?: boolean;
  sensitive?: boolean;
}

interface CreatePermissionInput {
  key: string;
  value?: unknown;
  mode?: PermissionMode;
  revocation_mode?: RevocationMode;
}

Audit Types

interface AuditContext {
  actor_id: string;
  actor_type: "api_key" | "jwt" | "system";
  source_ip?: string;
  request_id?: string;
}

interface AuditEntry {
  id: string;
  actor_id: string;
  actor_type: string;
  action: string;
  resource_type: string;
  resource_id: string | null;
  tenant_id: string | null;
  source_ip: string | null;
  request_id: string | null;
  before_state: Record<string, unknown> | null;
  after_state: Record<string, unknown> | null;
  metadata: Record<string, unknown>;
  created_at: string;
}

Consent Types

interface ConsentRecord {
  id: string;
  tenant_id: string;
  subject_id: string;
  purpose: string;
  granted: boolean;
  granted_at: string;
  revoked_at: string | null;
  expires_at: string | null;
  metadata: Record<string, unknown>;
}

Region Types

interface Region {
  id: string;
  display_name: string;
  slug: string;
  control_plane_url: string | null;
  database_url: string | null;
  is_primary: boolean;
  status: "active" | "draining" | "inactive";
  metadata: Record<string, unknown>;
}

Enums

enum IsolationStrategy {
  SHARED_RLS = "SHARED_RLS",
  SCHEMA_PER_TENANT = "SCHEMA_PER_TENANT",
  DB_PER_TENANT = "DB_PER_TENANT",
}

enum PermissionMode {
  LOCKED = "LOCKED",
  INHERITED = "INHERITED",
  DELEGATED = "DELEGATED",
}

enum RevocationMode {
  CASCADE = "CASCADE",
  SOFT = "SOFT",
  PERMANENT = "PERMANENT",
}

Validation Schemas (Zod)

import {
  SlugSchema,
  UUIDSchema,
  PaginationSchema,
  CreateTenantInputSchema,
  SetConfigInputSchema,
  CreatePermissionInputSchema,
  AuditLogQuerySchema,
  GrantConsentInputSchema,
  CreateRegionInputSchema,
} from "@stratum-hq/core";

SlugSchema.parse("valid_slug");     // passes
SlugSchema.parse("INVALID");        // throws ZodError

PaginationSchema.parse({ limit: 50 });    // passes
PaginationSchema.parse({ limit: 200 });   // throws (max 100)

Utility Functions

Ancestry Helpers

import {
  buildAncestryPath,
  parseAncestryPath,
  getDepth,
  isAncestorOf,
} from "@stratum-hq/core";

buildAncestryPath("/parent-uuid", "child-uuid");
// "/parent-uuid/child-uuid"

parseAncestryPath("/a/b/c");
// ["a", "b", "c"]

getDepth("/a/b/c");
// 2

isAncestorOf("/a/b", "/a/b/c");
// true

Error Classes

All errors extend StratumError, which extends Error:

import {
  StratumError,
  TenantNotFoundError,
  TenantArchivedError,
  TenantAlreadyExistsError,
  TenantHasChildrenError,
  TenantCycleDetectedError,
  ConfigLockedError,
  ConfigNotFoundError,
  PermissionLockedError,
  PermissionNotFoundError,
  PermissionRevocationDeniedError,
  UnauthorizedError,
  ForbiddenError,
  IsolationStrategyUnsupportedError,
} from "@stratum-hq/core";

Constants

import {
  MAX_TREE_DEPTH,        // 20
  MAX_SLUG_LENGTH,       // 63
  DEFAULT_CACHE_TTL_MS,  // 60_000
  DEFAULT_PAGE_SIZE,     // 50
  MAX_PAGE_SIZE,         // 100
  API_KEY_PREFIX,        // "sk_live_"
  API_KEY_BYTES,         // 32
  TENANT_HEADER,         // "X-Tenant-ID"
} from "@stratum-hq/core";