@portaidentity/server 1.7.0

package/dist/custom-claims/service.js

@@ -0,0 +1,296 @@
+/**
+ * Custom claims service — business logic layer.
+ *
+ * Orchestrates claim definition CRUD, value management, and token claims
+ * building. This is the primary public interface for the custom-claims
+ * module — callers should use these functions instead of accessing the
+ * repository or cache directly.
+ *
+ * Responsibilities:
+ * - Validate claim names (reserved, format) before create
+ * - Enforce uniqueness (application_id + claim_name)
+ * - Validate value types against definition types before set
+ * - Cache orchestration for definitions (cache-first reads, invalidation on writes)
+ * - Audit logging for all write operations (fire-and-forget)
+ * - Build custom claims for token issuance (filtered by token type)
+ *
+ * @see repository.ts — Database operations
+ * @see cache.ts — Redis cache for definitions
+ * @see validators.ts — Name and value validation
+ */
+import { insertDefinition as repoInsertDefinition, findDefinitionById as repoFindDefinitionById, updateDefinition as repoUpdateDefinition, deleteDefinition as repoDeleteDefinition, listDefinitionsByApplication as repoListDefinitions, claimNameExists, upsertValue as repoUpsertValue, findValue as repoFindValue, deleteValue as repoDeleteValue, getValuesForUser as repoGetValuesForUser, getValuesForUserByApp, } from './repository.js';
+import { getCachedDefinitions, setCachedDefinitions, invalidateDefinitionsCache, } from './cache.js';
+import { validateClaimName, validateClaimValue } from './validators.js';
+import { ClaimNotFoundError, ClaimValidationError } from './errors.js';
+import { writeAuditLog } from '../lib/audit-log.js';
+// ===========================================================================
+// Definition Management
+// ===========================================================================
+/**
+ * Create a custom claim definition for an application.
+ *
+ * Validates the claim name is not reserved, matches the required format,
+ * and is unique within the application. Invalidates the definitions cache
+ * after successful creation.
+ *
+ * @param input - Definition data to create
+ * @returns The newly created definition
+ * @throws ClaimValidationError if name is reserved, invalid format, or duplicate
+ */
+export async function createDefinition(input) {
+    // 1. Validate claim name format and reserved names
+    const nameValidation = validateClaimName(input.claimName);
+    if (!nameValidation.valid) {
+        throw new ClaimValidationError(nameValidation.reason);
+    }
+    // 2. Check uniqueness within the application
+    const exists = await claimNameExists(input.applicationId, input.claimName);
+    if (exists) {
+        throw new ClaimValidationError(`Claim name '${input.claimName}' already exists for this application`);
+    }
+    // 3. Insert into database
+    const definition = await repoInsertDefinition(input);
+    // 4. Invalidate definitions cache for this application
+    await invalidateDefinitionsCache(input.applicationId);
+    // 5. Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'claim.defined',
+        eventCategory: 'admin',
+        metadata: {
+            definitionId: definition.id,
+            applicationId: definition.applicationId,
+            claimName: definition.claimName,
+            claimType: definition.claimType,
+        },
+    });
+    return definition;
+}
+/**
+ * Update a claim definition (inclusion flags and description only).
+ *
+ * claimName and claimType cannot be changed — they define the claim's
+ * identity. Invalidates the definitions cache after update.
+ *
+ * @param id - Definition UUID
+ * @param input - Fields to update
+ * @returns Updated definition
+ * @throws ClaimNotFoundError if definition not found
+ */
+export async function updateDefinition(id, input) {
+    // 1. Verify definition exists (needed to get applicationId for cache invalidation)
+    const existing = await repoFindDefinitionById(id);
+    if (!existing) {
+        throw new ClaimNotFoundError(id);
+    }
+    // 2. Update in database
+    const updated = await repoUpdateDefinition(id, input);
+    // 3. Invalidate definitions cache for this application
+    await invalidateDefinitionsCache(existing.applicationId);
+    // 4. Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'claim.updated',
+        eventCategory: 'admin',
+        metadata: {
+            definitionId: id,
+            applicationId: existing.applicationId,
+            claimName: existing.claimName,
+            changes: input,
+        },
+    });
+    return updated;
+}
+/**
+ * Delete a claim definition (cascades to all associated values).
+ *
+ * Invalidates the definitions cache after deletion.
+ *
+ * @param id - Definition UUID
+ * @throws ClaimNotFoundError if definition not found
+ */
+export async function deleteDefinition(id) {
+    // 1. Verify definition exists (needed for cache invalidation and audit)
+    const existing = await repoFindDefinitionById(id);
+    if (!existing) {
+        throw new ClaimNotFoundError(id);
+    }
+    // 2. Delete from database (CASCADE removes values)
+    await repoDeleteDefinition(id);
+    // 3. Invalidate definitions cache for this application
+    await invalidateDefinitionsCache(existing.applicationId);
+    // 4. Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'claim.deleted',
+        eventCategory: 'admin',
+        metadata: {
+            definitionId: id,
+            applicationId: existing.applicationId,
+            claimName: existing.claimName,
+        },
+    });
+}
+/**
+ * Find a claim definition by ID.
+ *
+ * @param id - Definition UUID
+ * @returns Definition or null if not found
+ */
+export async function findDefinitionById(id) {
+    return repoFindDefinitionById(id);
+}
+/**
+ * List all claim definitions for an application. Cache-first.
+ *
+ * Checks Redis cache first. On cache miss, queries the database
+ * and populates the cache for subsequent requests.
+ *
+ * @param applicationId - Application UUID
+ * @returns Array of definitions
+ */
+export async function listDefinitions(applicationId) {
+    // 1. Check cache
+    const cached = await getCachedDefinitions(applicationId);
+    if (cached !== null) {
+        return cached;
+    }
+    // 2. Cache miss — query database
+    const definitions = await repoListDefinitions(applicationId);
+    // 3. Cache the result
+    await setCachedDefinitions(applicationId, definitions);
+    return definitions;
+}
+// ===========================================================================
+// Value Management
+// ===========================================================================
+/**
+ * Set a custom claim value for a user.
+ *
+ * Validates that the claim definition exists and the value matches
+ * the definition's claim type. Uses upsert semantics (insert or update).
+ *
+ * @param userId - User UUID
+ * @param claimId - Definition UUID
+ * @param value - The value to set (must match definition's claimType)
+ * @returns The upserted claim value
+ * @throws ClaimNotFoundError if definition not found
+ * @throws ClaimValidationError if value type mismatch
+ */
+export async function setValue(userId, claimId, value) {
+    // 1. Verify definition exists and get its type
+    const definition = await repoFindDefinitionById(claimId);
+    if (!definition) {
+        throw new ClaimNotFoundError(claimId);
+    }
+    // 2. Validate value matches definition type
+    const valueValidation = validateClaimValue(definition.claimType, value);
+    if (!valueValidation.valid) {
+        throw new ClaimValidationError(valueValidation.reason);
+    }
+    // 3. Upsert the value
+    const result = await repoUpsertValue(userId, claimId, value);
+    // 4. Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'claim.value.set',
+        eventCategory: 'admin',
+        userId,
+        metadata: {
+            definitionId: claimId,
+            claimName: definition.claimName,
+        },
+    });
+    return result;
+}
+/**
+ * Get a specific claim value for a user.
+ *
+ * @param userId - User UUID
+ * @param claimId - Definition UUID
+ * @returns Claim value or null if not set
+ */
+export async function getValue(userId, claimId) {
+    return repoFindValue(userId, claimId);
+}
+/**
+ * Delete a claim value for a user.
+ *
+ * @param userId - User UUID
+ * @param claimId - Definition UUID
+ * @throws ClaimNotFoundError if value not found
+ */
+export async function deleteValue(userId, claimId) {
+    const deleted = await repoDeleteValue(userId, claimId);
+    if (!deleted) {
+        throw new ClaimNotFoundError(`value for user ${userId}, claim ${claimId}`);
+    }
+    // Audit log (fire-and-forget)
+    void writeAuditLog({
+        eventType: 'claim.value.deleted',
+        eventCategory: 'admin',
+        userId,
+        metadata: { definitionId: claimId },
+    });
+}
+/**
+ * Get all claim values for a user (across all applications).
+ *
+ * Returns joined definition+value pairs for admin views.
+ *
+ * @param userId - User UUID
+ * @returns Array of definition+value pairs
+ */
+export async function getValuesForUser(userId) {
+    return repoGetValuesForUser(userId);
+}
+// ===========================================================================
+// Token Claims Building
+// ===========================================================================
+/**
+ * Build custom claims for inclusion in a token.
+ *
+ * Resolves the user's custom claim values for the specified application,
+ * filtered by the token type (id_token, access_token, or userinfo).
+ * Returns a flat object: { claimName: value, ... }
+ *
+ * Token type filtering:
+ * - id_token → only claims where includeInIdToken is true
+ * - access_token → only claims where includeInAccessToken is true
+ * - userinfo → only claims where includeInUserinfo is true
+ *
+ * @param userId - The user whose claims to resolve
+ * @param applicationId - The application whose claim definitions to use
+ * @param tokenType - Which token type is being built
+ * @returns Flat object with claim names as keys and values
+ */
+export async function buildCustomClaims(userId, applicationId, tokenType) {
+    // 1. Query all user's claim values for this application (with definitions)
+    const claimsWithValues = await getValuesForUserByApp(userId, applicationId);
+    // 2. Filter by token type inclusion flag and build result
+    const result = {};
+    for (const { definition, value } of claimsWithValues) {
+        // Check the appropriate inclusion flag based on token type
+        const included = isClaimIncluded(definition, tokenType);
+        if (included) {
+            result[definition.claimName] = value.value;
+        }
+    }
+    return result;
+}
+/**
+ * Check whether a claim definition should be included for a specific token type.
+ *
+ * @param definition - The claim definition with inclusion flags
+ * @param tokenType - The token type being built
+ * @returns true if the claim should be included
+ */
+function isClaimIncluded(definition, tokenType) {
+    switch (tokenType) {
+        case 'id_token':
+            return definition.includeInIdToken;
+        case 'access_token':
+            return definition.includeInAccessToken;
+        case 'userinfo':
+            return definition.includeInUserinfo;
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/custom-claims/service.js.map

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

package/dist/custom-claims/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Custom claims types and interfaces.
+ *
+ * Defines the data structures for custom claim definitions and values.
+ * Definitions are per-application (which claims exist and where to include
+ * them), values are per-user (actual claim data stored as JSONB).
+ *
+ * Includes database row interfaces, input types for create/update, a
+ * convenience joined type, and mapping functions to convert snake_case
+ * database rows to camelCase TypeScript objects.
+ *
+ * Database tables: custom_claim_definitions, custom_claim_values
+ * (see migration 007_custom_claims.sql)
+ */
+/** Supported custom claim value types (stored in claim_type column) */
+export type ClaimType = 'string' | 'number' | 'boolean' | 'json';
+/** Token types where a claim can be included — used for filtering at issuance */
+export type TokenType = 'id_token' | 'access_token' | 'userinfo';
+/**
+ * Full claim definition record as stored in the database.
+ * Maps to the `custom_claim_definitions` table columns (see migration 007).
+ * Definitions are scoped to an application — each app can have its own set
+ * of custom claims with independent inclusion rules.
+ */
+export interface CustomClaimDefinition {
+    id: string;
+    applicationId: string;
+    claimName: string;
+    claimType: ClaimType;
+    description: string | null;
+    includeInIdToken: boolean;
+    includeInAccessToken: boolean;
+    includeInUserinfo: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Raw database row from the custom_claim_definitions table (snake_case columns).
+ * Used by the repository layer; mapped to CustomClaimDefinition via mapRowToDefinition().
+ */
+export interface CustomClaimDefinitionRow {
+    id: string;
+    application_id: string;
+    claim_name: string;
+    claim_type: string;
+    description: string | null;
+    include_in_id_token: boolean;
+    include_in_access_token: boolean;
+    include_in_userinfo: boolean;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Input for creating a new claim definition.
+ * claimName and claimType are required and immutable once created.
+ * Token inclusion flags default to: id_token=false, access_token=true, userinfo=true.
+ */
+export interface CreateClaimDefinitionInput {
+    applicationId: string;
+    claimName: string;
+    claimType: ClaimType;
+    description?: string;
+    includeInIdToken?: boolean;
+    includeInAccessToken?: boolean;
+    includeInUserinfo?: boolean;
+}
+/**
+ * Input for updating an existing claim definition (partial).
+ * Only description and token inclusion flags are updatable — claimName
+ * and claimType define the claim identity and cannot be changed.
+ */
+export interface UpdateClaimDefinitionInput {
+    description?: string | null;
+    includeInIdToken?: boolean;
+    includeInAccessToken?: boolean;
+    includeInUserinfo?: boolean;
+}
+/**
+ * Full claim value record as stored in the database.
+ * Maps to the `custom_claim_values` table columns (see migration 007).
+ * Values are per-user, per-claim — stored as JSONB to support any type.
+ */
+export interface CustomClaimValue {
+    id: string;
+    userId: string;
+    claimId: string;
+    value: unknown;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Raw database row from the custom_claim_values table (snake_case columns).
+ * Used by the repository layer; mapped to CustomClaimValue via mapRowToValue().
+ */
+export interface CustomClaimValueRow {
+    id: string;
+    user_id: string;
+    claim_id: string;
+    value: unknown;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * A claim definition joined with its user value.
+ * Used when resolving all claims for a user (e.g., for token building).
+ */
+export interface CustomClaimWithValue {
+    definition: CustomClaimDefinition;
+    value: CustomClaimValue;
+}
+/**
+ * Map a database row to a CustomClaimDefinition object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The claim_type column is cast to ClaimType.
+ *
+ * @param row - Raw database row from the custom_claim_definitions table
+ * @returns Mapped definition with camelCase properties
+ */
+export declare function mapRowToDefinition(row: CustomClaimDefinitionRow): CustomClaimDefinition;
+/**
+ * Map a database row to a CustomClaimValue object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The value field is preserved as-is (JSONB
+ * already parsed by the pg driver).
+ *
+ * @param row - Raw database row from the custom_claim_values table
+ * @returns Mapped value with camelCase properties
+ */
+export declare function mapRowToValue(row: CustomClaimValueRow): CustomClaimValue;
+//# sourceMappingURL=types.d.ts.map

package/dist/custom-claims/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/custom-claims/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,uEAAuE;AACvE,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAEjE,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,cAAc,GAAG,UAAU,CAAC;AAMjE;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,uBAAuB,EAAE,OAAO,CAAC;IACjC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,UAAU,EAAE,IAAI,CAAC;IACjB,UAAU,EAAE,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAMD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,IAAI,CAAC;IACjB,UAAU,EAAE,IAAI,CAAC;CAClB;AAMD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,qBAAqB,CAAC;IAClC,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,wBAAwB,GAAG,qBAAqB,CAavF;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,gBAAgB,CASxE"}

package/dist/custom-claims/types.js

@@ -0,0 +1,61 @@
+/**
+ * Custom claims types and interfaces.
+ *
+ * Defines the data structures for custom claim definitions and values.
+ * Definitions are per-application (which claims exist and where to include
+ * them), values are per-user (actual claim data stored as JSONB).
+ *
+ * Includes database row interfaces, input types for create/update, a
+ * convenience joined type, and mapping functions to convert snake_case
+ * database rows to camelCase TypeScript objects.
+ *
+ * Database tables: custom_claim_definitions, custom_claim_values
+ * (see migration 007_custom_claims.sql)
+ */
+// ---------------------------------------------------------------------------
+// Database row mapping functions
+// ---------------------------------------------------------------------------
+/**
+ * Map a database row to a CustomClaimDefinition object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The claim_type column is cast to ClaimType.
+ *
+ * @param row - Raw database row from the custom_claim_definitions table
+ * @returns Mapped definition with camelCase properties
+ */
+export function mapRowToDefinition(row) {
+    return {
+        id: row.id,
+        applicationId: row.application_id,
+        claimName: row.claim_name,
+        claimType: row.claim_type,
+        description: row.description,
+        includeInIdToken: row.include_in_id_token,
+        includeInAccessToken: row.include_in_access_token,
+        includeInUserinfo: row.include_in_userinfo,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/**
+ * Map a database row to a CustomClaimValue object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The value field is preserved as-is (JSONB
+ * already parsed by the pg driver).
+ *
+ * @param row - Raw database row from the custom_claim_values table
+ * @returns Mapped value with camelCase properties
+ */
+export function mapRowToValue(row) {
+    return {
+        id: row.id,
+        userId: row.user_id,
+        claimId: row.claim_id,
+        value: row.value,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/custom-claims/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/custom-claims/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2HH,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAA6B;IAC9D,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,aAAa,EAAE,GAAG,CAAC,cAAc;QACjC,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAuB;QACtC,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,gBAAgB,EAAE,GAAG,CAAC,mBAAmB;QACzC,oBAAoB,EAAE,GAAG,CAAC,uBAAuB;QACjD,iBAAiB,EAAE,GAAG,CAAC,mBAAmB;QAC1C,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,GAAwB;IACpD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,OAAO,EAAE,GAAG,CAAC,QAAQ;QACrB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC"}

package/dist/custom-claims/validators.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Custom claim validators.
+ *
+ * Provides validation logic for claim names and values:
+ *   - Reserved claim name check (OIDC standard + Porta internal names)
+ *   - Claim name format validation (lowercase alphanumeric + underscores)
+ *   - Value type validation against claim definition type
+ *
+ * These validators are used by the service layer before any database
+ * operations to provide clear error messages.
+ */
+import type { ClaimType } from './types.js';
+/**
+ * OIDC standard and Porta reserved claim names.
+ *
+ * Custom claims cannot use any of these names to prevent conflicts with
+ * standard OIDC claims (RFC 7519, OpenID Connect Core 1.0 §5.1) and
+ * Porta's own internal claims (roles, permissions, org context).
+ */
+export declare const RESERVED_CLAIM_NAMES: ReadonlySet<string>;
+/**
+ * Check if a claim name is reserved (cannot be used as a custom claim).
+ *
+ * @param name - Claim name to check
+ * @returns true if the name is reserved
+ */
+export declare function isReservedClaimName(name: string): boolean;
+/**
+ * Validate a custom claim name.
+ *
+ * Rules:
+ * 1. Must not be empty
+ * 2. Must match format: lowercase alphanumeric + underscores, starting with a letter
+ * 3. Must be 1-100 characters
+ * 4. Must not be a reserved OIDC/Porta claim name
+ *
+ * @param name - Claim name to validate
+ * @returns Object with valid=true or valid=false with reason
+ */
+export declare function validateClaimName(name: string): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Validate that a claim value matches the expected type from the definition.
+ *
+ * Type rules:
+ * - string: typeof value === 'string'
+ * - number: typeof value === 'number' && isFinite(value) (NaN and Infinity rejected)
+ * - boolean: typeof value === 'boolean'
+ * - json: value !== null && typeof value === 'object' (arrays and objects allowed)
+ *
+ * @param claimType - Expected type from the claim definition
+ * @param value - The value to validate
+ * @returns Object with valid=true or valid=false with reason
+ */
+export declare function validateClaimValue(claimType: ClaimType, value: unknown): {
+    valid: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=validators.d.ts.map

package/dist/custom-claims/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/custom-claims/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAUnD,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAyBnF;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,OAAO,GACb;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAuCrC"}