fix(core): report every refusing AuthorizationStatus, not just Invalid (#159)

The OCPP 1.6 AuthorizationStatus enumeration (edition 2, section 7.2) has five
values and only Accepted permits charging. Blocked, Expired and ConcurrentTx are
refusals: the trace shows the same shape as an Invalid refusal, an Authorize
answered with a status that denies charging and then no transaction, and the
driver's session is over either way. The rule fired on Invalid alone, so a
blocked or expired token produced a clean report, and silence from a detector
reads as "this is not the problem", which is worse than having no rule.

All four refusals now report under FAILED_AUTHORIZATION with the status named in
the description. One code rather than four: the operator-facing question is the
same in every case, the specific status is on the failure object for anyone who
wants to branch on it, and every code is part of the published surface and of
the contract-v1 corpus, so codes are worth adding only when a consumer would act
differently. ConcurrentTx is included even though section 7.2 marks it as
relevant to StartTransaction.req, since seeing it on an Authorize response is
irregular but still a refusal. The suggested steps gain a line for that case.

Adds a refused-authorization scenario covering the three newly reported
statuses, which brings the corpus to 18; counts updated in the registry test,
the external fixture test, and both READMEs. No existing scenario's detected code
set changes, so the conformance contract is unchanged.

Left for its own issue: the rule only inspects Authorize responses, while
StartTransaction.conf and StopTransaction.conf also carry idTagInfo, and section
4.8 has the Central System verify the identifier again on StartTransaction, so a
session can start and then be deauthorized.

Author: sepehr-safari

.changeset/fix-authorization-refusal-statuses.md

@@ -0,0 +1,5 @@
+---
+'@ocpp-debugkit/toolkit': patch
+---
+
+Report every refusing `AuthorizationStatus` in `FAILED_AUTHORIZATION`, not just `Invalid` (#156). The OCPP 1.6 enumeration (edition 2, section 7.2) has five values and only `Accepted` permits charging, so `Blocked`, `Expired` and `ConcurrentTx` end a driver's session exactly as `Invalid` does. The rule fired on `Invalid` alone, which meant a blocked or expired token produced a clean report, and silence from a detector reads as "this is not the problem". All four refusals now report under the existing code, with the status named in the description, and the suggested steps mention the `ConcurrentTx` case. Adds a `refused-authorization` scenario covering the three newly reported statuses, bringing the corpus to 18.

CURRENT_STATE.md

@@ -100,6 +100,28 @@ these fixes introduce is required across detection.
 - Studio carries an independent copy of this matrix and needs the same
   transcription to stay equivalent under `contract-v1`
 
+### FAILED_AUTHORIZATION refusal statuses (Issue #156)
+
+- ✅ Rule 1 now reports every refusing value of the OCPP 1.6
+  `AuthorizationStatus` enumeration (edition 2, section 7.2): `Blocked`,
+  `Expired`, `Invalid` and `ConcurrentTx`. It previously fired on `Invalid`
+  alone, so a blocked or expired token produced a clean report
+- ✅ One code rather than four: the operator-facing question is the same in every
+  case, the status is named in the description, and severity stays `warning`.
+  Adding codes grows the published `FailureCode` union and the `contract-v1`
+  surface, so it is worth doing only when a consumer would act differently
+- ✅ New `refused-authorization` scenario (18 in the corpus) covering the three
+  newly reported statuses; counts updated in the registry test, the external
+  fixture test, and both READMEs
+- ✅ No existing scenario's detected code set changes, so the conformance
+  contract is unchanged
+- Out of scope, worth its own issue: the rule only inspects `Authorize`
+  responses, while `StartTransaction.conf` and `StopTransaction.conf` also carry
+  `idTagInfo` (section 4.8 re-verifies the identifier on `StartTransaction`, so a
+  session can start and then be deauthorized)
+- Studio's independent copy of this rule needs the same widening to stay
+  equivalent under `contract-v1`
+
 ### GitHub Infrastructure
 
 - ✅ GitHub milestones created (M0, M0.5, v0.1.0, v0.2.0, v0.3.0, v1.0.0)

README.md

@@ -22,7 +22,7 @@ validate behavior against known scenarios.
   firmware update failures, suspicious session duration, slow CSMS responses,
   heartbeat interval violations, meter value anomalies, unresponsive CSMS, and
   repeated boot notifications.
-- **Scenario Evaluator** — 17 predefined scenarios with expected failure
+- **Scenario Evaluator** — 18 predefined scenarios with expected failure
   outcomes for testing the analysis engine. Supports external scenario files.
 - **Replay Engine** — Deterministic, pure replay engine with step forward/back,
   jump-to-event, and configurable playback speed.

packages/toolkit/README.md

@@ -20,7 +20,7 @@ report generation, React components, and CLI.
   firmware update failures, suspicious session duration, slow CSMS responses,
   heartbeat interval violations, meter value anomalies, unresponsive CSMS, and
   repeated boot notifications.
-- **Scenario Evaluator** — 17 predefined scenarios with expected failure
+- **Scenario Evaluator** — 18 predefined scenarios with expected failure
   outcomes for testing the analysis engine. Supports external scenario files.
 - **Replay Engine** — Deterministic, pure replay engine with step forward/back,
   jump-to-event, and configurable playback speed. No timers or I/O.

packages/toolkit/src/core/detection.test.ts

@@ -126,6 +126,41 @@ describe('detectFailures', () => {
 
       expect(failures.filter((f) => f.code === 'FAILED_AUTHORIZATION')).toHaveLength(2);
     });
+
+    // OCPP 1.6 edition 2, section 7.2: AuthorizationStatus has five values and
+    // only Accepted permits charging. The rule used to fire on Invalid alone.
+    const authorizeWithStatus = (status: string): Event[] => [
+      makeEvent('evt-0001', 'msg-001', 'Call', 'Authorize', { idTag: 'SYNTHETIC-TAG-001' }, 1000),
+      makeEvent(
+        'evt-0002',
+        'msg-001',
+        'CallResult',
+        null,
+        { idTagInfo: { status } },
+        1500,
+        'CSMS_TO_CS',
+      ),
+    ];
+
+    it.each(['Invalid', 'Blocked', 'Expired', 'ConcurrentTx'])(
+      'detects %s as a refused authorization',
+      (status) => {
+        const events = authorizeWithStatus(status);
+        const failures = detectFailures(events, buildSessionTimeline(events)).filter(
+          (f) => f.code === 'FAILED_AUTHORIZATION',
+        );
+        expect(failures).toHaveLength(1);
+        expect(failures[0]?.severity).toBe('warning');
+        expect(failures[0]?.description).toContain(`"${status}"`);
+        expect(failures[0]?.eventIds).toEqual(['evt-0001', 'evt-0002']);
+      },
+    );
+
+    it('does not flag an unrecognized idTagInfo status', () => {
+      const events = authorizeWithStatus('NotAnAuthorizationStatus');
+      const failures = detectFailures(events, buildSessionTimeline(events));
+      expect(failures.some((f) => f.code === 'FAILED_AUTHORIZATION')).toBe(false);
+    });
   });
 
   describe('CONNECTOR_FAULT', () => {

packages/toolkit/src/core/detection.ts

@@ -4,7 +4,7 @@
  * 16 detection rules (v0.1 + v0.2 + v0.3):
  *
  * v0.1:
- * 1. FAILED_AUTHORIZATION — Authorize response with idTagInfo.status = "Invalid"
+ * 1. FAILED_AUTHORIZATION — Authorize response with a refusing idTagInfo.status
  * 2. CONNECTOR_FAULT — StatusNotification with status = "Faulted" during active session
  * 3. STATION_OFFLINE_DURING_SESSION — session has StartTransaction but no StopTransaction
  *
@@ -39,6 +39,7 @@ const SUGGESTED_STEPS: Record<FailureCode, string[]> = {
     'Verify the idTag is valid and not expired',
     'Check the CSMS local authorization list',
     'Ensure the idTag is not blocked or deactivated',
+    'For ConcurrentTx, check whether the idTag is still open on another transaction',
     'Review the Authorize response payload for rejection reason',
   ],
   CONNECTOR_FAULT: [
@@ -201,9 +202,20 @@ function getStatusNotificationErrorCode(event: Event): string | null {
 // Detection rules
 // ---------------------------------------------------------------------------
 
+/**
+ * The refusing values of the OCPP 1.6 `AuthorizationStatus` enumeration (edition
+ * 2, section 7.2). The enumeration has five values and only `Accepted` permits
+ * charging: `Blocked` and `Expired` are refusals of a known identifier,
+ * `Invalid` means the identifier is unknown, and `ConcurrentTx` means it is
+ * already in another transaction. Section 7.2 marks `ConcurrentTx` as only
+ * relevant to `StartTransaction.req`, so seeing it on an `Authorize` response is
+ * itself irregular, but it is still a refusal.
+ */
+const AUTHORIZATION_REFUSAL_STATUSES = new Set(['Blocked', 'Expired', 'Invalid', 'ConcurrentTx']);
+
 /**
  * Rule 1: FAILED_AUTHORIZATION
- * Detects Authorize responses where idTagInfo.status is "Invalid".
+ * Detects Authorize responses carrying an idTagInfo.status that refuses charging.
  */
 function detectFailedAuthorization(events: Event[]): Failure[] {
   const failures: Failure[] = [];
@@ -222,10 +234,10 @@ function detectFailedAuthorization(events: Event[]): Failure[] {
     if (!matchingCall) continue;
 
     const status = getAuthorizeStatus(event);
-    if (status === 'Invalid') {
+    if (status !== null && AUTHORIZATION_REFUSAL_STATUSES.has(status)) {
       failures.push({
         code: 'FAILED_AUTHORIZATION',
-        description: `Authorization rejected: idTag returned "Invalid" status (messageId: ${event.messageId})`,
+        description: `Authorization rejected: idTag returned "${status}" status (messageId: ${event.messageId})`,
         severity: SEVERITY.FAILED_AUTHORIZATION,
         eventIds: [matchingCall.id, event.id],
         suggestedSteps: SUGGESTED_STEPS.FAILED_AUTHORIZATION,

packages/toolkit/src/scenarios/__scenarios__/refused-authorization.ts

@@ -0,0 +1,122 @@
+export default {
+  name: 'refused-authorization',
+  description:
+    'Authorization refused three times with the non-Invalid statuses of OCPP 1.6 section 7.2: Blocked, Expired, ConcurrentTx. StartTransaction is not attempted. Expects FAILED_AUTHORIZATION failure.',
+  trace: {
+    traceId: 'scenario-refused-authorization',
+    metadata: {
+      stationId: 'CS-SYNTHETIC-017',
+      ocppVersion: '1.6',
+      source: 'synthetic-scenario',
+      description:
+        'Station boots, connector prepares, then three idTags are refused in turn: one Blocked, one Expired, one ConcurrentTx. Section 7.2 marks ConcurrentTx as relevant to StartTransaction, so an Authorize response carrying it is irregular; it is included because the rule treats every non-Accepted status as a refusal wherever it appears. The connector returns to Available without a transaction.',
+    },
+    events: [
+      {
+        timestamp: '2026-01-15T09:00:00.000Z',
+        direction: 'CS_TO_CSMS',
+        message: [
+          2,
+          'msg-001',
+          'BootNotification',
+          {
+            chargePointVendor: 'SyntheticVendor',
+            chargePointModel: 'SM-100',
+            chargePointSerialNumber: 'CS-SYNTHETIC-017',
+            firmwareVersion: '1.0.0',
+          },
+        ],
+      },
+      {
+        timestamp: '2026-01-15T09:00:00.500Z',
+        direction: 'CSMS_TO_CS',
+        message: [
+          3,
+          'msg-001',
+          {
+            currentTime: '2026-01-15T09:00:00.500Z',
+            interval: 300,
+            status: 'Accepted',
+          },
+        ],
+      },
+      {
+        timestamp: '2026-01-15T09:00:05.000Z',
+        direction: 'CS_TO_CSMS',
+        message: [
+          2,
+          'msg-002',
+          'StatusNotification',
+          { connectorId: 0, status: 'Available', errorCode: 'NoError' },
+        ],
+      },
+      {
+        timestamp: '2026-01-15T09:00:05.500Z',
+        direction: 'CSMS_TO_CS',
+        message: [3, 'msg-002', {}],
+      },
+      {
+        timestamp: '2026-01-15T09:00:10.000Z',
+        direction: 'CS_TO_CSMS',
+        message: [
+          2,
+          'msg-003',
+          'StatusNotification',
+          { connectorId: 1, status: 'Preparing', errorCode: 'NoError' },
+        ],
+      },
+      {
+        timestamp: '2026-01-15T09:00:10.500Z',
+        direction: 'CSMS_TO_CS',
+        message: [3, 'msg-003', {}],
+      },
+      {
+        timestamp: '2026-01-15T09:00:20.000Z',
+        direction: 'CS_TO_CSMS',
+        message: [2, 'msg-004', 'Authorize', { idTag: 'SYNTHETIC-TAG-201' }],
+      },
+      {
+        timestamp: '2026-01-15T09:00:20.500Z',
+        direction: 'CSMS_TO_CS',
+        message: [3, 'msg-004', { idTagInfo: { status: 'Blocked' } }],
+      },
+      {
+        timestamp: '2026-01-15T09:00:35.000Z',
+        direction: 'CS_TO_CSMS',
+        message: [2, 'msg-005', 'Authorize', { idTag: 'SYNTHETIC-TAG-202' }],
+      },
+      {
+        timestamp: '2026-01-15T09:00:35.500Z',
+        direction: 'CSMS_TO_CS',
+        message: [3, 'msg-005', { idTagInfo: { status: 'Expired' } }],
+      },
+      {
+        timestamp: '2026-01-15T09:00:50.000Z',
+        direction: 'CS_TO_CSMS',
+        message: [2, 'msg-006', 'Authorize', { idTag: 'SYNTHETIC-TAG-203' }],
+      },
+      {
+        timestamp: '2026-01-15T09:00:50.500Z',
+        direction: 'CSMS_TO_CS',
+        message: [3, 'msg-006', { idTagInfo: { status: 'ConcurrentTx' } }],
+      },
+      {
+        timestamp: '2026-01-15T09:01:05.000Z',
+        direction: 'CS_TO_CSMS',
+        message: [
+          2,
+          'msg-007',
+          'StatusNotification',
+          { connectorId: 1, status: 'Available', errorCode: 'NoError' },
+        ],
+      },
+      {
+        timestamp: '2026-01-15T09:01:05.500Z',
+        direction: 'CSMS_TO_CS',
+        message: [3, 'msg-007', {}],
+      },
+    ],
+  },
+  expectedFailures: ['FAILED_AUTHORIZATION'],
+  assertions: [{ type: 'failure_count', params: { code: 'FAILED_AUTHORIZATION', min: 3 } }],
+};

packages/toolkit/src/scenarios/index.test.ts

@@ -20,6 +20,7 @@ import {
   unresponsiveCsmsScenario,
   firmwareUpdateSuccessScenario,
   firmwareUpdateFailureScenario,
+  refusedAuthorizationScenario,
 } from './index.js';
 import { parseTrace, buildSessionTimeline, detectFailures } from '../core/index.js';
 
@@ -28,8 +29,8 @@ import { parseTrace, buildSessionTimeline, detectFailures } from '../core/index.
 // ---------------------------------------------------------------------------
 
 describe('scenario registry', () => {
-  it('exports exactly 17 scenarios', () => {
-    expect(scenarios).toHaveLength(17);
+  it('exports exactly 18 scenarios', () => {
+    expect(scenarios).toHaveLength(18);
   });
 
   it('exports scenario names in order', () => {
@@ -51,6 +52,7 @@ describe('scenario registry', () => {
       'unresponsive-csms',
       'firmware-update-success',
       'firmware-update-failure',
+      'refused-authorization',
     ]);
   });
 
@@ -213,6 +215,21 @@ describe('scenario engine integration', () => {
     const failures = detectFailures(result.events, sessions);
     expect(failures.some((f) => f.code === 'FIRMWARE_UPDATE_FAILURE')).toBe(true);
   });
+
+  it('refused-authorization: detects FAILED_AUTHORIZATION for each non-Invalid refusal', () => {
+    const trace = JSON.stringify(refusedAuthorizationScenario.trace);
+    const result = parseTrace(trace);
+    const sessions = buildSessionTimeline(result.events);
+    const failures = detectFailures(result.events, sessions).filter(
+      (f) => f.code === 'FAILED_AUTHORIZATION',
+    );
+    expect(failures).toHaveLength(3);
+    expect(failures.map((f) => f.description.match(/"(\w+)" status/)?.[1])).toEqual([
+      'Blocked',
+      'Expired',
+      'ConcurrentTx',
+    ]);
+  });
 });
 
 // ---------------------------------------------------------------------------

packages/toolkit/src/scenarios/index.ts

@@ -22,6 +22,7 @@ import heartbeatIrregular from './__scenarios__/heartbeat-irregular.js';
 import unresponsiveCsms from './__scenarios__/unresponsive-csms.js';
 import firmwareUpdateSuccess from './__scenarios__/firmware-update-success.js';
 import firmwareUpdateFailure from './__scenarios__/firmware-update-failure.js';
+import refusedAuthorization from './__scenarios__/refused-authorization.js';
 
 // ---------------------------------------------------------------------------
 // Scenarios derived from core fixtures
@@ -70,6 +71,7 @@ const heartbeatIrregularScenario: Scenario = heartbeatIrregular as unknown as Sc
 const unresponsiveCsmsScenario: Scenario = unresponsiveCsms as unknown as Scenario;
 const firmwareUpdateSuccessScenario: Scenario = firmwareUpdateSuccess as unknown as Scenario;
 const firmwareUpdateFailureScenario: Scenario = firmwareUpdateFailure as unknown as Scenario;
+const refusedAuthorizationScenario: Scenario = refusedAuthorization as unknown as Scenario;
 
 // ---------------------------------------------------------------------------
 // Registry
@@ -93,6 +95,7 @@ export const scenarios = [
   unresponsiveCsmsScenario,
   firmwareUpdateSuccessScenario,
   firmwareUpdateFailureScenario,
+  refusedAuthorizationScenario,
 ] as const;
 
 export const scenarioNames = [
@@ -113,6 +116,7 @@ export const scenarioNames = [
   'unresponsive-csms',
   'firmware-update-success',
   'firmware-update-failure',
+  'refused-authorization',
 ] as const;
 
 export {
@@ -133,6 +137,7 @@ export {
   unresponsiveCsmsScenario,
   firmwareUpdateSuccessScenario,
   firmwareUpdateFailureScenario,
+  refusedAuthorizationScenario,
 };
 
 export { compareScenarioReports } from './compare.js';

tests/external-fixture/test.mjs

@@ -158,8 +158,8 @@ const scenarios = await import('@ocpp-debugkit/toolkit/scenarios');
 
 assert(Array.isArray(scenarios.scenarios), 'scenarios is an array');
 assert(
-  scenarios.scenarios.length === 17,
-  `17 scenarios exported (got ${scenarios.scenarios.length})`,
+  scenarios.scenarios.length === 18,
+  `18 scenarios exported (got ${scenarios.scenarios.length})`,
 );
 assert(typeof scenarios.getScenario === 'function', 'getScenario is a function');
 assert(scenarios.getScenario('normal-session') !== undefined, 'normal-session scenario exists');