Module/pam - Koya Documentation

Minimal wrapper around Linux PAM for validating credentials from a lockscreen or similar UI.

Import #

Types #

AuthOptions

Options passed to authenticate().

service string optional - PAM service name. Defaults to 'login'.
user string - Username to authenticate.
password string - Password to verify.

AuthResult

Object resolved (or rejected) by authenticate().

ok boolean - true on success, false on failure.
pamCode number - PAM return code (0 for success).
message string optional - Error message on failure.

Functions #

authenticate

Runs a PAM conversation on a worker thread and resolves on the engine thread.

service defaults to 'login' if omitted.
Resolves only after PAM authentication and account checks succeed; otherwise rejects with the same object shape. Empty account passwords are disallowed. Native password copies are erased after use.

authenticate(options: AuthOptions): Promise<AuthResult>

Example #

Validate a user's credentials against the system PAM stack. This is the core pattern for implementing a lockscreen or any UI that requires local authentication.

import * as PAM from 'Module/pam';
import * as Log from 'Helix/Log';

try {
  const res = await PAM.authenticate({ service: 'login', user: 'alice', password: 'secret' });
  Log.info('Authenticated: ' + res.ok);
} catch (e) {
  Log.error('Auth failed: ' + (e?.message ?? String(e)));
}

Notes #

The plugin links against libpam. Ensure PAM is available on your system.
Authentication uses a non-echo prompt for the password and does not log secrets.
For testing, see assets/tests/pam_test.js. You can set environment variables: KOYA_PAM_SERVICE (default login), KOYA_PAM_USER (defaults to current user), KOYA_PAM_PASSWORD (enables positive test path).

<- Module/hypr Standard Library ->