@orieken/saturday-keycloak

Portable certificate identities and Keycloak adapters for automated tests. ESM only; requires Node.js 22 or later. Licensed under Apache-2.0.

Install

Core, manual-browser, and CLI operations have no runtime dependencies:

npm install @orieken/saturday-keycloak

For the /playwright adapter, also install @playwright/[email protected]. For /cucumber, install @playwright/[email protected], @cucumber/[email protected], and @orieken/[email protected]. These are optional peers: install the combination required by the export you use. Cucumber versions satisfying ^11.3.0 || ^12.9.0 are supported by the peer contract. The certificate path convention helper is included; no local tarballs are required.

Certificate identities

import { FileCertificateProvider } from '@orieken/saturday-keycloak';
import { certificateContextOptions } from '@orieken/saturday-keycloak/playwright';

const provider = new FileCertificateProvider('/absolute/certificates', {
  'test/customer-a': {
    cert: 'customer-a/cert.pem',
    key: 'customer-a/key.pem',
  },
});
const identity = { namespace: 'test', name: 'customer-a' };
const target = {
  origins: ['https://store.example.test:8443', 'https://identity.example.test:9443'],
  issuer: 'https://identity.example.test:9443/realms/test',
};
const options = await certificateContextOptions(provider, identity, target);
// Pass options to browser.newContext(options).

The certificate root must be absolute. Identity paths are relative to that root; traversal and symlink escapes are rejected. Certificates must be current and match their private keys. Use exact HTTPS origins without trailing slashes. Server certificate validation remains enabled. Your application supplies roles, origins, identities, trust configuration, and certificate provisioning.

Exports

• Root: IdentityRef, FileCertificateProvider, PkiCommandAdapter, ServiceTokenClient, and KeycloakAdminAdapter.
• /playwright: certificate context/API options, createCertificateContext, createCertificateTest, and saturdayConvention path mapping.
• /cucumber: createCertificateCucumberHooks and installCertificateCucumberHooks. Register after installing SaturdayWorld; do not register Saturday's default context hook alongside these hooks.
• /manual: manualBrowserManifest provides references for Chrome/Edge native certificate setup; the caller performs installation.
• /cli: runCli, also exposed as the saturday-keycloak command.

Provision, renew, revoke, and cleanup are explicit operator actions. The PKI adapter runs a configured executable with structured arguments and a capability file. The admin adapter requires a token file and namespace prefix, refuses to overwrite an existing certificate identity, and limits deletion to the configured namespace prefix. Network operations have bounded timeouts.

The service-token helper checks audience, scope, and expiry to detect caller mistakes; receiving APIs must verify JWT signatures. Keep private keys and token files outside source control and build artifacts.

CLI

Create a local JSON configuration (absolute paths refer to your machine):

{
  "root": "/absolute/certificates",
  "identities": {
    "test/customer-a": { "cert": "customer-a/cert.pem", "key": "customer-a/key.pem" }
  },
  "target": {
    "origins": ["https://identity.example.test:9443"],
    "issuer": "https://identity.example.test:9443/realms/test"
  },
  "trustFiles": ["/absolute/trust/root-ca.pem"]
}

saturday-keycloak /absolute/config.json inspect test customer-a
saturday-keycloak /absolute/config.json manifest test customer-a chrome

Operator actions additionally require pki or admin configuration; see the exported TypeScript declarations for adapter options. CLI errors intentionally avoid printing sensitive configuration.

Develop and pack

This directory is self-contained and can be copied into its own repository.

npm install
npm run typecheck
npm test
npm run build
npm pack

npm pack and publication run typechecking, all unit tests, and the production build through prepack. Only production ESM, declarations, README, LICENSE, and NOTICE are included in the tarball. Test output is excluded. Optional runner peers are installed as development dependencies for build and tests.