signalk-server/dist/oidc/types.d.ts

An implementation of a [Signal K](http://signalk.org) server for boats.

/**
 * Signal K permission type
 */
export type SignalKPermission = 'readonly' | 'readwrite' | 'admin';
/**
 * OIDC Configuration - merged from environment variables and security.json
 */
export interface OIDCConfig {
    enabled: boolean;
    issuer: string;
    clientId: string;
    clientSecret: string;
    redirectUri: string;
    scope: string;
    defaultPermission: SignalKPermission;
    autoCreateUsers: boolean;
    /** Groups that grant admin permission */
    adminGroups?: string[];
    /** Groups that grant readwrite permission */
    readwriteGroups?: string[];
    /**
     * ID token claim key for groups (default: 'groups').
     * Common alternatives: 'roles', 'memberOf', 'cognito:groups'
     * Note: Groups must be present in the ID token, not the userinfo endpoint.
     * Both array and single string values are supported.
     */
    groupsAttribute?: string;
    /**
     * Display name for the OIDC provider shown on the login button.
     * Default: 'SSO Login'
     */
    providerName: string;
    /**
     * If true, automatically redirect to OIDC login when not authenticated.
     * Default: false
     */
    autoLogin: boolean;
}
/**
 * Partial OIDC config for merging from different sources
 */
export interface PartialOIDCConfig {
    enabled?: boolean;
    issuer?: string;
    clientId?: string;
    clientSecret?: string;
    redirectUri?: string;
    scope?: string;
    defaultPermission?: SignalKPermission;
    autoCreateUsers?: boolean;
    adminGroups?: string[];
    readwriteGroups?: string[];
    groupsAttribute?: string;
    providerName?: string;
    autoLogin?: boolean;
}
/**
 * OIDC Authorization State - stored in cookie during auth flow
 */
export interface OIDCAuthState {
    state: string;
    codeVerifier: string;
    nonce: string;
    redirectUri: string;
    originalUrl: string;
    createdAt: number;
}
/**
 * OIDC Token Response
 */
export interface OIDCTokens {
    accessToken: string;
    idToken: string;
    refreshToken?: string;
    expiresIn?: number;
    tokenType: string;
}
/**
 * OIDC User Info - extracted from ID token or userinfo endpoint
 */
export interface OIDCUserInfo {
    sub: string;
    email?: string;
    name?: string;
    preferredUsername?: string;
    groups?: string[];
}
/**
 * OIDC user identifier stored in security.json
 */
export interface OIDCUserIdentifier {
    sub: string;
    issuer: string;
}
/**
 * Discovery document cache entry
 */
export interface DiscoveryCache {
    metadata: OIDCProviderMetadata;
    fetchedAt: number;
    expiresAt: number;
}
/**
 * OIDC Provider Metadata (subset of OpenID Discovery)
 */
export interface OIDCProviderMetadata {
    issuer: string;
    authorization_endpoint: string;
    token_endpoint: string;
    userinfo_endpoint?: string;
    jwks_uri: string;
    response_types_supported: string[];
    code_challenge_methods_supported?: string[];
    /** Endpoint for RP-initiated logout (optional, not all providers support) */
    end_session_endpoint?: string;
}
/**
 * OIDC Error codes
 */
export type OIDCErrorCode = 'DISCOVERY_FAILED' | 'INVALID_STATE' | 'STATE_EXPIRED' | 'INVALID_TOKEN' | 'TOKEN_EXCHANGE_FAILED' | 'USER_INFO_FAILED' | 'CONFIG_INVALID' | 'PKCE_FAILED' | 'NOT_CONFIGURED' | 'USER_CREATION_DENIED';
/**
 * OIDC Error class
 */
export declare class OIDCError extends Error {
    code: OIDCErrorCode;
    cause?: Error | undefined;
    constructor(message: string, code: OIDCErrorCode, cause?: Error | undefined);
}
/**
 * Default OIDC configuration values
 */
export declare const OIDC_DEFAULTS: Omit<OIDCConfig, 'issuer' | 'clientId' | 'clientSecret' | 'redirectUri'>;
/**
 * State cookie configuration
 */
export declare const STATE_COOKIE_NAME = "OIDC_STATE";
export declare const STATE_MAX_AGE_MS: number;
/**
 * Crypto service interface for OIDC state encryption.
 *
 * tokensecurity implements this by providing a derived secret.
 * OIDC handles its own encryption - tokensecurity knows nothing
 * about OIDC state structure (separation of concerns).
 */
export interface OIDCCryptoService {
    /**
     * Get the secret for OIDC state encryption.
     * This is derived from the master secret, ensuring OIDC
     * never has access to the JWT signing key.
     */
    getStateEncryptionSecret(): string;
}
/**
 * Criteria for looking up users by external provider metadata.
 * Designed to support multiple auth providers, not just OIDC.
 */
export interface ProviderUserLookup {
    /** Provider identifier (e.g., 'oidc', 'ldap', 'saml') */
    provider: string;
    /** Provider-specific lookup criteria */
    criteria: Record<string, string>;
}
/**
 * Generic user service interface for external authentication providers.
 * Named generically to support future auth providers beyond OIDC.
 *
 * This interface abstracts user storage so authentication providers
 * don't need to know about the underlying storage mechanism
 * (array, SQLite, PostgreSQL, etc.).
 */
export interface ExternalUserService {
    /** Find a user by external provider metadata */
    findUserByProvider(lookup: ProviderUserLookup): Promise<ExternalUser | null>;
    /** Find a user by username (for collision detection) */
    findUserByUsername(username: string): Promise<ExternalUser | null>;
    /** Create a new user */
    createUser(user: ExternalUser): Promise<void>;
    /** Update an existing user's type and/or provider data */
    updateUser(username: string, updates: {
        type?: string;
        providerData?: Record<string, unknown>;
    }): Promise<void>;
}
/**
 * User representation for external auth providers.
 * This is a subset of the full User type that external providers need.
 */
export interface ExternalUser {
    username: string;
    type: string;
    /** Provider-specific identifier (e.g., OIDC sub+issuer) */
    providerData?: Record<string, unknown>;
}
//# sourceMappingURL=types.d.ts.map