@xemahq/workload-identity

Reads a workload's identity declaration from its environment

Overview

A workload authenticates by presenting the token its platform mounted for it, not a client secret. This package reads the XEMA_WORKLOAD_IDENTITY declaration (realm, audience, token file, service id) and turns it into the configuration that @xemahq/identity-client uses for the exchange. It has no dependencies and performs no network or file access itself.

When to use it

• Use it in any workload (service, worker, Job, CronJob) that authenticates with its mounted attestation.
• The exchange itself is done by @xemahq/identity-client.

Installation

pnpm add @xemahq/workload-identity

Usage

import {
  readWorkloadIdentityDeclaration,
  singleRealmOf,
  workloadAttestationExchange,
} from '@xemahq/workload-identity';
import { WorkloadContextSource, fileCredentialReader } from '@xemahq/identity-client';

const declaration = readWorkloadIdentityDeclaration((n) => process.env[n]);
if (declaration !== null) {
  const source = new WorkloadContextSource(
    workloadAttestationExchange({
      declaration,
      realm: singleRealmOf(declaration),
      identityApiUrl, // resolved from the service registry, not from an env var
      readCredential: fileCredentialReader(declaration.attestationFile),
    }),
  );
  const context = await source.getContext();
}

readWorkloadIdentityDeclaration returns null when the variable is unset and throws WorkloadIdentityDeclarationError when it is present but malformed. parseWorkloadIdentityDeclaration(json) parses the value directly; missing or unknown fields are refused.

Configuration

| Name | Description | |---|---| | XEMA_WORKLOAD_IDENTITY (WORKLOAD_IDENTITY_ENV) | JSON declaration emitted by the platform. | | realm or realms | Exactly one of the two. realm is one non-empty string; realms is a non-empty array of distinct non-empty strings, for a workload that acts in several realms. Both, neither, a duplicate entry, or realms with placement: dispatched is refused. The parsed declaration always exposes realms; singleRealmOf(declaration) returns the sole realm and throws when there are several. | | audience | Trust domain the minted context is issued for. | | attestationFile | Absolute path of the mounted token. | | serviceId | Name this workload registers under. | | placement | Optional, deployed (default) or dispatched (WorkloadPlacement): who scheduled the workload. A dispatched workload is never registered as a service instance. |

workloadAttestationExchange is per realm: it takes declaration, the one realm to speak for (singleRealmOf(declaration) for a single-realm workload), identityApiUrl and readCredential, plus optional refreshBeforeExpirySeconds and member (for a process that composes several services).

License

Apache-2.0 © Xema — xema.dev