This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step

Platform Identity, Session And Impersonation — Policy And Sequence Catalog

• Status: SOURCE-RECONCILED PLATFORM POLICY/DIAGRAM INPUT / NO RUNTIME CHANGE
• Current source baseline: qa/master@3c084671c034f8f5136b02dce990ecff6c66d107
• Source authority: PLATFORM_IDENTITY_SESSION_IMPERSONATION_SOURCE_AUTHORITY.md
• Rebuild packet: PLATFORM_IDENTITY_SESSION_IMPERSONATION_REBUILD_PACKET.md
• Phase implementation: USER HOLD

---

1. Core Policy Boundaries

Actor != Subject
Authenticated != Authorized
Session active != Privileged reauthentication current
Impersonation != Role acceptance
Password changed != All sessions revoked
Provider identity != Local actor

1.1 Current versus target labels

• CURRENT SOURCE-RECONCILED: behavior visible in inspected source.
• TARGET DESIGN: required rebuild contract, not current Runtime.
• OPEN POLICY: must not be invented by an implementation writer.

---

2. Current Login Sequence

sequenceDiagram
    actor User
    participant Login as login.php
    participant DB as MySQL T_USER
    participant Password as Password Helper
    participant Session as PHP Session

    User->>Login: username + password
    Login->>DB: find active user by username
    DB-->>Login: user/password/client/role
    Login->>Password: verify modern or legacy hash
    alt invalid
        Login-->>User: generic sign-in failure
    else valid
        opt legacy or needs rehash
            Login->>DB: CAS password hash upgrade
            alt row changed != 1
                Login-->>User: sign-in unavailable
            end
        end
        Login->>Session: session_regenerate_id(true)
        Login->>Session: store original user/client/role fields
        Login->>DB: update LAST_LOGIN
        Login-->>User: redirect to admin/default page
    end

Current non-implication:

Password verified
!= account/session policy fully satisfied

---

3. Current Session State

stateDiagram-v2
    [*] --> Anonymous
    Anonymous --> Authenticated: successful login + session fields
    Authenticated --> Impersonating: IMPERSONATE session object written
    Impersonating --> Authenticated: impersonation object removed
    Authenticated --> Anonymous: logout / PHP expiry / missing session
    Impersonating --> Anonymous: logout / PHP expiry / missing session

    note right of Authenticated
      One current 20-hour TTL is configured.
      Idle, absolute and revocation states
      are not separately persisted.
    end note

Target adds explicit:

REAUTH_REQUIRED
EXPIRED
REVOKED
UNKNOWN

---

4. Current Direct User Request

sequenceDiagram
    actor User
    participant Session
    participant Compat as Scalar Helpers
    participant Typed as Tenant Context Adapter
    participant Handler

    User->>Session: request with PHP session
    Session-->>Compat: login_id / username / CLIENT_ID / role
    Compat-->>Handler: effective scalar user and tenant
    opt strict route
        Session->>Typed: construct direct context
        Typed-->>Handler: actor=user, subject=user, tenant=session, STRICT
    end

A route that does not opt into typed context may use only the scalar compatibility result.

---

5. Current User Impersonation

sequenceDiagram
    actor Admin as Physical Super Admin
    participant API as Super-admin command
    participant DB
    participant Session
    participant Typed as Tenant Context Adapter
    participant App as Tenant Application

    Admin->>API: start impersonation(target tenant, target user)
    API->>DB: verify target user belongs to tenant
    DB-->>API: target identity
    API->>Session: store original actor + target subject/tenant
    API-->>Admin: redirect
    Admin->>App: tenant application request
    App->>Typed: reconstruct impersonation context
    Typed-->>App: actor=super-admin, subject=target user, tenant=target

Current gaps:

• no visible reason reference;
• no explicit impersonation expiry;
• no visible session ID rotation at start/end;
• prohibited actions remain caller-specific.

---

6. Current Tenant-Only Impersonation

sequenceDiagram
    actor Admin as Physical Super Admin
    participant Console as Admin Console
    participant Session
    participant Typed as Tenant Context Adapter
    participant Page as Tenant Page

    Admin->>Console: open selected tenant main app
    Console->>Session: TARGET_USER_ID=0, TARGET_CLIENT_ID=tenant
    Admin->>Page: open tenant page
    Page->>Typed: build impersonation context
    Typed-->>Page: actor=super-admin, subject=null, tenant=target

Required warning:

Tenant-only support context
!= a real target role/user session
!= target-role acceptance evidence

---

7. Current Admin API Override

sequenceDiagram
    actor Admin as Physical Super Admin
    participant API
    participant Adapter as Strict Tenant Adapter
    participant Handler

    Admin->>API: allowlisted request + target tenant
    API->>Adapter: override requested/allowed + authorization ref
    alt impersonation active or override not allowed
        Adapter-->>Admin: forbidden/invalid context
    else valid
        Adapter-->>Handler: actor=super-admin, subject=null, target tenant, STRICT
    end

This is not persisted session impersonation.

---

8. Current Password Change And Session Gap

sequenceDiagram
    actor User
    participant Command as Change Password
    participant DB
    participant Session

    User->>Command: current password + new password
    Command->>DB: load effective user/client
    Command->>DB: verify and update hash
    DB-->>Command: changed
    Command-->>User: success
    Note over Session: no explicit rotate/revoke/other-session disposition in helper

Target command returns explicit session dispositions.

---

9. Current Logout

sequenceDiagram
    actor User
    participant Page as index.php ?page=logout
    participant Session
    participant Browser

    User->>Page: GET logout
    Page->>Session: unset selected fields
    Page->>Session: session_destroy()
    Page-->>Browser: JavaScript redirect

Open policy includes command method, cookie deletion, revocation and cross-runtime behavior.

---

10. Target Identity/Session Sequence

sequenceDiagram
    actor User
    participant React
    participant Next as Next.js Adapter
    participant Identity as Identity Application
    participant Session as Session Authority
    participant Repo as User Repository
    participant Audit

    User->>React: sign in
    React->>Next: credential request
    Next->>Identity: AuthenticateUser
    Identity->>Repo: locate unambiguous active identity
    Identity->>Identity: verify/upgrade credential
    Identity->>Session: rotate/issue authoritative session
    Identity->>Audit: record safe result
    Session-->>Identity: session reference/expiry
    Identity-->>Next: safe identity result
    Next-->>React: authenticated state + landing

---

11. Target Impersonation Sequence

sequenceDiagram
    actor Admin
    participant UI as React Admin UI
    participant Next
    participant Identity
    participant Policy
    participant Session
    participant Audit

    Admin->>UI: target + reason + Start
    UI->>Next: StartImpersonation
    Next->>Identity: physical actor/session + target
    Identity->>Policy: capability + reauth + target checks
    alt denied
        Identity-->>UI: stable denial
    else allowed
        Identity->>Session: rotate and bind delegation
        Identity->>Audit: actor/subject/tenant/reason/start/expiry
        Identity-->>UI: impersonation ref + banner state
    end

---

12. Target End-Impersonation Sequence

sequenceDiagram
    actor Admin
    participant UI
    participant Identity
    participant Session
    participant Audit

    Admin->>UI: End impersonation
    UI->>Identity: EndImpersonation(current ref)
    Identity->>Session: remove delegation / rotate session
    Identity->>Audit: record end and result
    Identity-->>UI: physical actor restored + safe landing

---

13. PHP And Next.js Coexistence

13.1 Allowed read bridge

sequenceDiagram
    actor User
    participant Browser
    participant Authority as One Session Authority
    participant PHP as PHP Adapter
    participant Next as Next.js Adapter

    Browser->>PHP: current PHP route
    PHP->>Authority: validate same session
    Authority-->>PHP: actor/subject/tenant
    Browser->>Next: migrated route
    Next->>Authority: validate same session
    Authority-->>Next: same actor/subject/tenant

13.2 Prohibited dual authority

flowchart LR
    Browser --> PHP[PHP Session A]
    Browser --> Next[Next.js Session B]
    PHP -. different expiry/revocation .- Next

The migration must not leave two independent accepted sessions for the same cohort.

---

14. Identity Policy Decisions

ID	Decision	Status
IDN-POL-010	username namespace / login realm	OPEN
IDN-POL-020	password policy	OPEN
IDN-POL-030	legacy hash retirement evidence	OPEN
IDN-POL-040	idle timeout	OPEN
IDN-POL-050	absolute timeout	OPEN
IDN-POL-060	trusted proxy for Secure cookie	OPEN
IDN-POL-070	session revocation authority	OPEN
IDN-POL-080	password change/reset revocation	OPEN
IDN-POL-090	throttling/lockout	OPEN
IDN-POL-100	MFA scope	OPEN
IDN-POL-110	impersonation reason reference	RECOMMENDED
IDN-POL-120	impersonation expiry	OPEN
IDN-POL-130	session rotation on start/end	RECOMMENDED / EVIDENCE REQUIRED
IDN-POL-140	impersonation prohibited actions	OPEN
IDN-POL-150	tenant-only support mode	PRESERVE WITH LIMIT
IDN-POL-160	privileged reauthentication	OPEN
IDN-POL-170	logout command/transport	RECOMMENDED / HELD
IDN-POL-180	single PHP/Next.js session authority	REQUIRED BEFORE P12
IDN-POL-190	implementation library/provider	DEFERRED

---

15. Unknown-Result Rule

Most identity/session commands should complete synchronously, but network loss can still make the browser uncertain.

Response missing
-> reread authoritative session/impersonation/password disposition
-> do not submit a second start/reset/change blindly
-> resume only the missing boundary

Examples:

• impersonation may already be active;
• password may already be changed;
• current session may already be revoked;
• logout may have completed even if redirect failed.

---

16. Update Triggers

Update this catalog when accepted behavior changes:

• login lookup/realm;
• password hash/policy;
• cookie/session lifetime;
• proxy/secure-cookie logic;
• session issue/rotate/revoke;
• impersonation fields/start/end/expiry;
• actor/subject/tenant semantics;
• password reset/change session disposition;
• service/integration identity;
• PHP/Next.js bridge;
• privileged reauthentication;
• stable errors or support readback.

Diagrams remain documentation input; they do not activate implementation.

---

Source: docs/processes/PLATFORM_IDENTITY_SESSION_IMPERSONATION_POLICY_AND_SEQUENCE.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.