@portaidentity/server 1.7.0

package/dist/organizations/slugs.js

@@ -0,0 +1,130 @@
+/**
+ * Slug generation and validation utilities.
+ *
+ * Organization slugs are URL-safe identifiers used in path-based
+ * multi-tenancy (e.g., /{slug}/.well-known/openid-configuration).
+ * They must be 3–100 characters, lowercase alphanumeric with hyphens,
+ * and cannot be a reserved system word.
+ *
+ * This module provides:
+ * - `generateSlug(name)` — Derive a slug from an organization name
+ * - `validateSlug(slug)` — Check format and reserved-word rules
+ * - `RESERVED_SLUGS` — The set of words that cannot be used as slugs
+ */
+// ---------------------------------------------------------------------------
+// Reserved slugs
+// ---------------------------------------------------------------------------
+/**
+ * Reserved slugs that cannot be used as organization slugs.
+ * These conflict with system routes, well-known paths, or
+ * could cause confusion with internal functionality.
+ */
+export const RESERVED_SLUGS = new Set([
+    // System routes
+    'admin',
+    'api',
+    'health',
+    'static',
+    '.well-known',
+    // Auth-related paths
+    'login',
+    'logout',
+    'callback',
+    'register',
+    'signup',
+    'auth',
+    'oauth',
+    'oidc',
+    'token',
+    'jwks',
+    // Application paths
+    'portal',
+    'dashboard',
+    'settings',
+    'account',
+    // Well-known files
+    'favicon.ico',
+    'robots.txt',
+    'sitemap.xml',
+]);
+// ---------------------------------------------------------------------------
+// Slug format
+// ---------------------------------------------------------------------------
+/**
+ * Slug format regex: 3–100 characters, lowercase alphanumeric + hyphens.
+ * Must start and end with an alphanumeric character (no leading/trailing hyphens).
+ * The middle section allows 1–98 characters of alphanumeric + hyphens.
+ */
+const SLUG_REGEX = /^[a-z0-9][a-z0-9-]{1,98}[a-z0-9]$/;
+// ---------------------------------------------------------------------------
+// Slug generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate a URL-safe slug from an organization name.
+ *
+ * Transformation rules:
+ * 1. Convert to lowercase
+ * 2. Replace non-alphanumeric characters with hyphens
+ * 3. Collapse multiple consecutive hyphens into one
+ * 4. Trim leading and trailing hyphens
+ * 5. Truncate to 100 characters (trimming trailing hyphens after truncation)
+ *
+ * Returns an empty string for empty/whitespace-only input — the caller
+ * (service layer) is responsible for validation.
+ *
+ * @param name - Organization name to derive a slug from
+ * @returns Generated slug string
+ */
+export function generateSlug(name) {
+    if (!name || !name.trim()) {
+        return '';
+    }
+    const slug = name
+        .toLowerCase()
+        // Replace any character that's not a-z, 0-9, or hyphen with a hyphen
+        .replace(/[^a-z0-9-]/g, '-')
+        // Collapse consecutive hyphens into a single hyphen
+        .replace(/-+/g, '-')
+        // Remove leading and trailing hyphens
+        .replace(/^-+|-+$/g, '');
+    // Truncate to 100 characters, then trim any trailing hyphen caused by truncation
+    return slug.slice(0, 100).replace(/-+$/, '');
+}
+/**
+ * Validate a slug against format and reserved word rules.
+ *
+ * Checks (in order):
+ * 1. Minimum length (3 characters)
+ * 2. Maximum length (100 characters)
+ * 3. Format (lowercase alphanumeric + hyphens, no leading/trailing hyphens)
+ * 4. Not a reserved word
+ *
+ * Does NOT check uniqueness — that's the repository/service layer's job.
+ *
+ * @param slug - Slug string to validate
+ * @returns Object with isValid boolean and optional error message
+ */
+export function validateSlug(slug) {
+    // Check minimum length
+    if (slug.length < 3) {
+        return { isValid: false, error: 'Slug must be at least 3 characters' };
+    }
+    // Check maximum length
+    if (slug.length > 100) {
+        return { isValid: false, error: 'Slug must be at most 100 characters' };
+    }
+    // Check format: lowercase alphanumeric + hyphens, no leading/trailing hyphens
+    if (!SLUG_REGEX.test(slug)) {
+        return {
+            isValid: false,
+            error: 'Slug must contain only lowercase letters, numbers, and hyphens, ' +
+                'and cannot start or end with a hyphen',
+        };
+    }
+    // Check reserved words
+    if (RESERVED_SLUGS.has(slug)) {
+        return { isValid: false, error: `Slug "${slug}" is reserved and cannot be used` };
+    }
+    return { isValid: true };
+}
+//# sourceMappingURL=slugs.js.map

package/dist/organizations/slugs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugs.js","sourceRoot":"","sources":["../../src/organizations/slugs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IACzD,gBAAgB;IAChB,OAAO;IACP,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,aAAa;IAEb,qBAAqB;IACrB,OAAO;IACP,QAAQ;IACR,UAAU;IACV,UAAU;IACV,QAAQ;IACR,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;IACP,MAAM;IAEN,oBAAoB;IACpB,QAAQ;IACR,WAAW;IACX,UAAU;IACV,SAAS;IAET,mBAAmB;IACnB,aAAa;IACb,YAAY;IACZ,aAAa;CACd,CAAC,CAAC;AAEH,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,GAAG,mCAAmC,CAAC;AAEvD,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,IAAI,GAAG,IAAI;SACd,WAAW,EAAE;QACd,qEAAqE;SACpE,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;QAC5B,oDAAoD;SACnD,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;QACpB,sCAAsC;SACrC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE3B,iFAAiF;IACjF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAYD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,uBAAuB;IACvB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;IACzE,CAAC;IAED,uBAAuB;IACvB,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC;IAC1E,CAAC;IAED,8EAA8E;IAC9E,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EACH,kEAAkE;gBAClE,uCAAuC;SAC1C,CAAC;IACJ,CAAC;IAED,uBAAuB;IACvB,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,IAAI,kCAAkC,EAAE,CAAC;IACpF,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC"}

package/dist/organizations/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Organization types and interfaces.
+ *
+ * Defines the data structures for the organization (tenant) model,
+ * including the full database record, input types for create/update,
+ * branding configuration, and pagination helpers. Also provides
+ * a mapping function to convert snake_case database rows to
+ * camelCase TypeScript objects.
+ *
+ * These types are the foundation that all other organization modules
+ * depend on (repository, cache, service, routes).
+ */
+import type { TwoFactorPolicy } from '../two-factor/types.js';
+import type { LoginMethod } from '../clients/types.js';
+/** Organization status values — matches the DB CHECK constraint */
+export type OrganizationStatus = 'active' | 'suspended' | 'archived';
+/**
+ * Full organization record as stored in the database.
+ * Maps to the `organizations` table columns (see migration 002).
+ */
+export interface Organization {
+    id: string;
+    name: string;
+    slug: string;
+    status: OrganizationStatus;
+    isSuperAdmin: boolean;
+    brandingLogoUrl: string | null;
+    brandingFaviconUrl: string | null;
+    brandingPrimaryColor: string | null;
+    brandingCompanyName: string | null;
+    brandingCustomCss: string | null;
+    defaultLocale: string;
+    /** Controls whether 2FA is required for org members */
+    twoFactorPolicy: TwoFactorPolicy;
+    /**
+     * Default login methods for all clients in this organization.
+     *
+     * Always non-empty (the DB column has `NOT NULL DEFAULT ARRAY['password',
+     * 'magic_link']` and the service layer rejects empty inputs). A client
+     * inherits this list when its own `loginMethods` is `null`.
+     */
+    defaultLoginMethods: LoginMethod[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Input for creating a new organization.
+ * Slug is auto-generated from name if not provided.
+ */
+export interface CreateOrganizationInput {
+    name: string;
+    slug?: string;
+    defaultLocale?: string;
+    branding?: BrandingInput;
+    /**
+     * Optional override for the org-wide default login methods.
+     * If omitted, the database `DEFAULT ARRAY['password', 'magic_link']`
+     * applies. The service layer validates + normalizes the array.
+     */
+    defaultLoginMethods?: LoginMethod[];
+}
+/** Input for updating an existing organization (partial). */
+export interface UpdateOrganizationInput {
+    name?: string;
+    defaultLocale?: string;
+    twoFactorPolicy?: TwoFactorPolicy;
+    branding?: BrandingInput;
+    /**
+     * New org-wide default login methods. Must be a non-empty array of
+     * valid {@link LoginMethod} values; the service layer enforces both.
+     */
+    defaultLoginMethods?: LoginMethod[];
+}
+/** Branding configuration input — all fields optional/nullable. */
+export interface BrandingInput {
+    logoUrl?: string | null;
+    faviconUrl?: string | null;
+    primaryColor?: string | null;
+    companyName?: string | null;
+    customCss?: string | null;
+}
+/** Options for listing organizations (paginated). */
+export interface ListOrganizationsOptions {
+    page: number;
+    pageSize: number;
+    status?: OrganizationStatus;
+    search?: string;
+    sortBy?: 'name' | 'created_at';
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Paginated result wrapper — generic so it can be reused for other
+ * list endpoints beyond organizations.
+ */
+export interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+/** Raw database row from the organizations table (snake_case columns). */
+export interface OrganizationRow {
+    id: string;
+    name: string;
+    slug: string;
+    status: string;
+    is_super_admin: boolean;
+    branding_logo_url: string | null;
+    branding_favicon_url: string | null;
+    branding_primary_color: string | null;
+    branding_company_name: string | null;
+    branding_custom_css: string | null;
+    default_locale: string;
+    two_factor_policy: string;
+    default_login_methods: string[];
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Map a database row to an Organization object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The `status` string is cast to
+ * `OrganizationStatus` — the DB CHECK constraint guarantees it
+ * is one of the valid values.
+ *
+ * @param row - Raw database row from the organizations table
+ * @returns Mapped Organization object with camelCase properties
+ */
+export declare function mapRowToOrganization(row: OrganizationRow): Organization;
+/** Counts of child entities that will be cascade-deleted with an organization. */
+export interface CascadeCounts {
+    applications: number;
+    clients: number;
+    users: number;
+    roles: number;
+    permissions: number;
+    claim_definitions: number;
+}
+/** Result of a successful organization destroy operation. */
+export interface DestroyResult {
+    organization: Organization;
+    cascadeCounts: CascadeCounts;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/organizations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/organizations/types.ts"],"names":[],"mappings":"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"}

package/dist/organizations/types.js

@@ -0,0 +1,49 @@
+/**
+ * Organization types and interfaces.
+ *
+ * Defines the data structures for the organization (tenant) model,
+ * including the full database record, input types for create/update,
+ * branding configuration, and pagination helpers. Also provides
+ * a mapping function to convert snake_case database rows to
+ * camelCase TypeScript objects.
+ *
+ * These types are the foundation that all other organization modules
+ * depend on (repository, cache, service, routes).
+ */
+/**
+ * Map a database row to an Organization object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The `status` string is cast to
+ * `OrganizationStatus` — the DB CHECK constraint guarantees it
+ * is one of the valid values.
+ *
+ * @param row - Raw database row from the organizations table
+ * @returns Mapped Organization object with camelCase properties
+ */
+export function mapRowToOrganization(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        slug: row.slug,
+        status: row.status,
+        isSuperAdmin: row.is_super_admin,
+        brandingLogoUrl: row.branding_logo_url,
+        brandingFaviconUrl: row.branding_favicon_url,
+        brandingPrimaryColor: row.branding_primary_color,
+        brandingCompanyName: row.branding_company_name,
+        brandingCustomCss: row.branding_custom_css,
+        defaultLocale: row.default_locale,
+        twoFactorPolicy: row.two_factor_policy,
+        // Defensive default: the DB column is NOT NULL with a sensible
+        // default, but if a stale cache or test fixture omits the field
+        // we still surface a usable value.
+        defaultLoginMethods: (row.default_login_methods ?? [
+            'password',
+            'magic_link',
+        ]),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/organizations/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/organizations/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAmJH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAoB;IACvD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE,GAAG,CAAC,MAA4B;QACxC,YAAY,EAAE,GAAG,CAAC,cAAc;QAChC,eAAe,EAAE,GAAG,CAAC,iBAAiB;QACtC,kBAAkB,EAAE,GAAG,CAAC,oBAAoB;QAC5C,oBAAoB,EAAE,GAAG,CAAC,sBAAsB;QAChD,mBAAmB,EAAE,GAAG,CAAC,qBAAqB;QAC9C,iBAAiB,EAAE,GAAG,CAAC,mBAAmB;QAC1C,aAAa,EAAE,GAAG,CAAC,cAAc;QACjC,eAAe,EAAE,GAAG,CAAC,iBAAoC;QACzD,+DAA+D;QAC/D,gEAAgE;QAChE,mCAAmC;QACnC,mBAAmB,EAAE,CAAC,GAAG,CAAC,qBAAqB,IAAI;YACjD,UAAU;YACV,YAAY;SACb,CAAkB;QACnB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC"}

package/dist/rbac/cache.d.ts

@@ -0,0 +1,110 @@
+/**
+ * RBAC cache — Redis-backed fast lookup layer.
+ *
+ * Provides get/set/invalidate operations for RBAC data stored in Redis:
+ *   - `rbac:role:{id}` — Individual role objects (for admin lookups)
+ *   - `rbac:user-roles:{userId}` — User's role slugs (for token claims)
+ *   - `rbac:user-perms:{userId}` — User's permission slugs (for token claims)
+ *
+ * The user-roles and user-permissions caches store slug arrays (string[])
+ * rather than full objects because token claims only need slugs. This
+ * reduces cache memory usage and serialization overhead on the hot path.
+ *
+ * All Redis errors are caught and logged — cache failures never propagate
+ * to callers. The system gracefully degrades to direct database lookups
+ * when Redis is unavailable.
+ *
+ * TTL: 5 minutes (balance between freshness and performance).
+ *
+ * Invalidation triggers:
+ * - Role updated/deleted → invalidateRoleCache()
+ * - Role-permission mapping changed → invalidateAllUserRbacCaches()
+ * - User-role assignment changed → invalidateUserRbacCache()
+ */
+import type { Role } from './types.js';
+/**
+ * Get a cached role by ID.
+ *
+ * Returns null on cache miss, invalid JSON, or Redis error.
+ * Callers should fall back to the database on null.
+ *
+ * @param id - Role UUID
+ * @returns Cached role or null
+ */
+export declare function getCachedRole(id: string): Promise<Role | null>;
+/**
+ * Cache a role by ID.
+ *
+ * Stores the full Role object as JSON with a 5-minute TTL.
+ * Date fields are serialized to ISO 8601 strings automatically.
+ *
+ * @param role - Role to cache
+ */
+export declare function setCachedRole(role: Role): Promise<void>;
+/**
+ * Invalidate a cached role.
+ *
+ * Should be called after any role update or deletion.
+ *
+ * @param id - Role UUID
+ */
+export declare function invalidateRoleCache(id: string): Promise<void>;
+/**
+ * Get cached user role slugs (for token claims).
+ *
+ * Returns null on cache miss, indicating the caller should resolve
+ * from the database and cache the result.
+ *
+ * @param userId - User UUID
+ * @returns Cached array of role slugs, or null on miss
+ */
+export declare function getCachedUserRoles(userId: string): Promise<string[] | null>;
+/**
+ * Cache user role slugs.
+ *
+ * Stores the slug array as JSON with a 5-minute TTL.
+ *
+ * @param userId - User UUID
+ * @param roleSlugs - Array of role slug strings
+ */
+export declare function setCachedUserRoles(userId: string, roleSlugs: string[]): Promise<void>;
+/**
+ * Get cached user permission slugs (for token claims).
+ *
+ * Returns null on cache miss, indicating the caller should resolve
+ * from the database and cache the result.
+ *
+ * @param userId - User UUID
+ * @returns Cached array of permission slugs, or null on miss
+ */
+export declare function getCachedUserPermissions(userId: string): Promise<string[] | null>;
+/**
+ * Cache user permission slugs.
+ *
+ * Stores the slug array as JSON with a 5-minute TTL.
+ *
+ * @param userId - User UUID
+ * @param permissionSlugs - Array of permission slug strings
+ */
+export declare function setCachedUserPermissions(userId: string, permissionSlugs: string[]): Promise<void>;
+/**
+ * Invalidate all user-related RBAC cache (roles + permissions).
+ *
+ * Called when a user's role assignments change. Deletes both the
+ * role slugs cache and permission slugs cache for the user.
+ *
+ * @param userId - User UUID
+ */
+export declare function invalidateUserRbacCache(userId: string): Promise<void>;
+/**
+ * Invalidate all user RBAC caches (roles + permissions) for all users.
+ *
+ * Called when role-permission mappings change, since we cannot easily
+ * enumerate which users have a specific role from Redis alone. Uses
+ * SCAN to find and delete matching keys without blocking Redis.
+ *
+ * This is a relatively expensive operation but role-permission changes
+ * are infrequent admin operations, so the trade-off is acceptable.
+ */
+export declare function invalidateAllUserRbacCaches(): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/rbac/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/rbac/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAsBvC;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAWpE;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAU7D;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnE;AAMD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAUjF;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3F;AAMD;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAUvF;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC,CAcf;AAMD;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3E;AAED;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAuBjE"}