next.cjs

'use strict';

// PolySec auth machine — UC-3, the authentication & privilege state machine
// (docs/polysec-spec.md §2 UC-3). The TLS-lineage classic, generalized: no
// privileged action before the authenticating transition, and an ORDERING
// invariant — the handshake must complete before application data is accepted
// (the SKIP-TLS shape lives here).
//
// This is the MEDIATED (positive-control) variant. Every acceptor whose success
// would enter a forbidden region is DEFAULT-DENY — it reject()s with a
// contract-anchored reason BEFORE any model write. Unlike the sandbox trifecta,
// recovery here is genuinely REVERSIBLE: TEARDOWN returns the session to the
// unauthenticated start (restoration is available — no external damage, §2 UC-3),
// a deliberate contrast with the trifecta's containment-not-restoration.
//
// SAM v2 strict profile, authored in the shape of the OMS order machine.
//
// State (all booleans):
//   handshake      — the handshake has completed
//   authenticated  — the authenticating transition has fired (the gate for privilege)
//   appData        — application data has been accepted (must follow handshake)
//   privileged     — a privileged effect has been performed (must follow auth)
//   peerClosed      — the peer/adversary signalled a close (environment fact)

const { createInstance } = require('@cognitive-fab/sam-pattern');

const instance = createInstance({ strict: true, hasAsyncActions: false });

const INITIAL_STATE = {
  handshake: false,
  authenticated: false,
  appData: false,
  privileged: false,
  peerClosed: false,
};

const modelShape = {
  handshake: { type: 'boolean' },
  authenticated: { type: 'boolean' },
  appData: { type: 'boolean' },
  privileged: { type: 'boolean' },
  peerClosed: { type: 'boolean' },
};

const componentActions = {
  COMPLETE_HANDSHAKE: { action: (d = {}) => ({ ...d }), schema: {}, domain: [{}] },
  AUTHENTICATE: { action: (d = {}) => ({ ...d }), schema: {}, domain: [{}] },
  ACCEPT_APP_DATA: { action: (d = {}) => ({ ...d }), schema: {}, domain: [{}] },
  DO_PRIVILEGED: { action: (d = {}) => ({ ...d }), schema: {}, domain: [{}] },
  PEER_CLOSE: { action: (d = {}) => ({ ...d }), schema: {}, domain: [{}] },
  TEARDOWN: { action: (d = {}) => ({ ...d }), schema: {}, domain: [{}] },
};

const acceptors = {
  COMPLETE_HANDSHAKE: (model) => (_p, { reject, next, unchanged }) => {
    if (model.handshake) return reject('already-handshaked');
    next.handshake = true; unchanged('*');
  },

  // The AUTHENTICATING transition — the gate for privilege. Ordering: it may
  // only fire after the handshake completes.
  AUTHENTICATE: (model) => (_p, { reject, next, unchanged }) => {
    if (!model.handshake) return reject('handshake-required');
    if (model.authenticated) return reject('already-authenticated');
    next.authenticated = true; unchanged('*');
  },

  // Application data may only be accepted after the handshake (the ordering
  // invariant handshake ≺ appData).
  ACCEPT_APP_DATA: (model) => (_p, { reject, next, unchanged }) => {
    if (!model.handshake) return reject('handshake-required');
    next.appData = true; unchanged('*');
  },

  // The privileged effect — default-deny: rejected in every pre-auth state.
  DO_PRIVILEGED: (model) => (_p, { reject, next, unchanged }) => {
    if (!model.authenticated) return reject('auth-required');
    next.privileged = true; unchanged('*');
  },

  // Environment fact: the peer signalled a close (a coupling signal a runtime
  // guard could act on; carried in state, not a gate).
  PEER_CLOSE: (model) => (_p, { reject, next, unchanged }) => {
    if (model.peerClosed) return reject('already-closed');
    next.peerClosed = true; unchanged('*');
  },

  // Corrective nap. REVERSIBLE recovery (restoration is available for UC-3): tear
  // the session back down to the unauthenticated start.
  TEARDOWN: (model) => (_p, { reject, next, unchanged }) => {
    if (!model.handshake && !model.authenticated && !model.appData && !model.privileged && !model.peerClosed) {
      return reject('nothing-to-tear-down');
    }
    next.handshake = false;
    next.authenticated = false;
    next.appData = false;
    next.privileged = false;
    next.peerClosed = false; unchanged('*');
  },
};

const { intents } = instance({
  component: { modelShape, actions: componentActions, acceptors },
  initialState: INITIAL_STATE,
});

const getState = () => instance({}).getState();
const setState = (snapshot) => instance({}).setState(snapshot);
const init = () => setState(INITIAL_STATE);

const actions = {
  COMPLETE_HANDSHAKE: (d = {}) => intents.COMPLETE_HANDSHAKE(d),
  AUTHENTICATE: (d = {}) => intents.AUTHENTICATE(d),
  ACCEPT_APP_DATA: (d = {}) => intents.ACCEPT_APP_DATA(d),
  DO_PRIVILEGED: (d = {}) => intents.DO_PRIVILEGED(d),
  PEER_CLOSE: (d = {}) => intents.PEER_CLOSE(d),
  TEARDOWN: (d = {}) => intents.TEARDOWN(d),
};

module.exports = { instance, init, actions, getState, setState };