Handling CAEP and RISC events

import { EVENT, SignalsReceiver, type SignalEvent } from 'saml2-sp-nodejs';

const signals = new SignalsReceiver({ transmitter, tls, onEndSessions });

signals.on(EVENT.credentialChange, async (event: SignalEvent) => {
  await audit.write('credential-change', event.subject.person, event.payload);
});

// Every event, of any type, after the type's own handlers:
signals.on('*', (event) => metrics.count(event.type));

await signals.start();

interface SignalEvent {
  type: string;                       // the event type URI, e.g. EVENT.sessionRevoked
  payload: Record<string, unknown>;   // the event's own members (below)
  subject: {
    person?: string;                  // an iss_sub subject's sub, e.g. 'urn:uuid:…'
    email?: string;                   // an email subject
    idpSession?: string;              // a complex subject's session: the SAML SessionIndex
  };
  sessions: string[];                 // the local sessions it names (from track())
  ended: boolean;                     // whether the receiver ended them
  jti: string;                        // the SET's id
  iat?: number;                       // when the SET was issued
  txn?: string;                       // the transaction id, when the transmitter sent one
}

import { CAEP_EVENTS, EVENT, RISC_EVENTS, SignalsReceiver } from 'saml2-sp-nodejs';

new SignalsReceiver({
  transmitter, tls, onEndSessions,
  // Ask for every CAEP and RISC type (the default asks for the ten in DEFAULT_EVENTS_REQUESTED).
  eventsRequested: [...CAEP_EVENTS, ...RISC_EVENTS],
  // End sessions on these (the default is DEFAULT_ENDING_EVENTS, five types).
  endOn: [EVENT.sessionRevoked, EVENT.accountDisabled, EVENT.accountPurged,
          EVENT.credentialCompromise, EVENT.sessionsRevoked, EVENT.riskLevelChange],
});

signals.on(EVENT.sessionRevoked, (event) => {
  // The sessions are already ended (onEndSessions ran). Record why, for the person's next sign-in page.
  const why = (event.payload.reason_user as Record<string, string> | undefined)?.en;
  for (const id of event.sessions) signedOutReasons.set(id, why ?? 'Signed out at the identity provider.');
});

signals.on(EVENT.credentialChange, async (event) => {
  const { credential_type, change_type } = event.payload as { credential_type: string; change_type: string };
  // A password changed elsewhere: ask the person to sign in again here too, but not mid-request.
  if (credential_type === 'password' && change_type !== 'create') {
    for (const id of event.sessions) await sessions.markForReauthentication(id);
  }
});

signals.on(EVENT.tokenClaimsChange, async (event) => {
  const claims = event.payload.claims as Record<string, unknown>;
  for (const id of event.sessions) await sessions.update(id, { staleAttributes: Object.keys(claims) });
});

signals.on(EVENT.assuranceLevelChange, async (event) => {
  // Remember the level, so a page that needs multi-factor can ask for a step-up when it fell.
  for (const id of event.sessions) await sessions.update(id, { acr: event.payload.current_level });
});

signals.on(EVENT.deviceComplianceChange, async (event) => {
  // Not ended by default: a non-compliant device may still read, but not write.
  if (event.payload.current_status === 'not-compliant') {
    for (const id of event.sessions) await sessions.update(id, { readOnly: true });
  }
});

signals.on(EVENT.sessionEstablished, (event) => {
  audit.write('idp-sign-in', event.subject.person, { acr: event.payload.acr, amr: event.payload.amr });
});

signals.on(EVENT.sessionPresented, (event) => {
  // Keep a local session alive while its IdP session is in use elsewhere.
  for (const id of event.sessions) sessions.touch(id);
});

signals.on(EVENT.riskLevelChange, async (event) => {
  const { current_level, principal } = event.payload as { current_level: string; principal: string };
  // End the person's sessions only when their risk is HIGH, rather than on every change.
  if (principal === 'USER' && current_level === 'HIGH' && event.sessions.length) {
    await endMySessions(event.sessions, 'Your account was flagged as high risk.');
  }
});

signals.on(EVENT.accountDisabled, async (event) => {
  // Sessions are already ended. Also refuse new local sign-ins until account-enabled arrives.
  await accounts.block(event.subject.person!, event.payload.reason ?? 'disabled at the identity provider');
});

signals.on(EVENT.accountEnabled, (event) => accounts.unblock(event.subject.person!));

signals.on(EVENT.accountPurged, async (event) => {
  // Remove or anonymise what the application keeps about the person.
  await profiles.deleteBySubject(event.subject.person!);
});

signals.on(EVENT.credentialCompromise, async (event) => {
  await security.alert(`compromised ${event.payload.credential_type} for ${event.subject.person}`);
});

signals.on(EVENT.accountCredentialChangeRequired, async (event) => {
  // Send the person to the identity provider's password change on their next page.
  for (const id of event.sessions) await sessions.update(id, { mustChangeCredential: true });
});

signals.on(EVENT.identifierChanged, async (event) => {
  // The subject is the old address; the receiver matched sessions by email through it.
  if (event.subject.email) await profiles.renameEmail(event.subject.email, event.payload['new-value'] as string | undefined);
});

signals.on(EVENT.identifierRecycled, async (event) => {
  // Anything keyed by this address belonged to someone else: unlink it.
  if (event.subject.email) await profiles.unlinkEmail(event.subject.email);
});

signals.on(EVENT.recoveryActivated, (event) => security.notice(`recovery started for ${event.subject.person}`));

signals.on(EVENT.recoveryInformationChanged, (event) => audit.write('recovery-info-changed', event.subject.person));

signals.on(EVENT.optOutEffective, (event) => accounts.setSignals(event.subject.person!, false));
signals.on(EVENT.optIn, (event) => accounts.setSignals(event.subject.person!, true));

signals.on(EVENT.streamUpdated, (event) => {
  if (event.payload.status !== 'enabled') ops.alert(`the signals stream is ${event.payload.status}: ${event.payload.reason ?? ''}`);
});