Skip to content

Platform Identity, Session And Impersonation — Capability Rebuild Packet

  • Packet status: DETAILED SOURCE-RECONCILED PLATFORM INPUT / NO IMPLEMENTATION ACTIVATION
  • Source authority: PLATFORM_IDENTITY_SESSION_IMPERSONATION_SOURCE_AUTHORITY.md
  • Current source baseline: qa/master@3c084671c034f8f5136b02dce990ecff6c66d107
  • Target stack: React identity UI + Next.js request/session adapters + framework-independent TypeScript identity/session services
  • Database order: MySQL first; PostgreSQL after React + Next.js + MySQL stabilization
  • Phase implementation: USER HOLD
  • Effects: documentation only

1. Required Platform Outcome

A rebuilt system must preserve one explainable identity chain for every request.

Credential or service binding
-> authenticated physical actor
-> authoritative session
-> optional impersonation/delegation
-> effective subject
-> tenant execution context
-> authorization decision
-> application command/query
-> audit and exact readback

1.1 User result

A user can:

  • sign in and land on an authorized default page;
  • understand when a session expired or was revoked;
  • change their own password through explicit reauthentication;
  • sign out from the current session;
  • when supported, inspect and revoke their other sessions;
  • receive a clear result without exposing credential internals.

1.2 Administrator result

An authorized administrator can:

  • identify the physical actor, effective subject and tenant separately;
  • begin and end a bounded impersonation session;
  • see an explicit impersonation banner and start time;
  • know which actions are unavailable while impersonating;
  • reset a user password without silently claiming all sessions were revoked;
  • inspect safe session/impersonation metadata;
  • correlate a support incident with request/session/impersonation references.

1.3 System/integration result

A job or provider callback executes only with:

  • explicit tenant binding;
  • explicit system/integration actor;
  • source name;
  • request/correlation ID;
  • authorization reference when required;
  • credential owner reference;
  • no browser-session fallback.

1.4 Non-goals

Do not create:

  • generalized identity-provider product scope without a selected need;
  • a customer-specific login fork;
  • provider identity as local authorization;
  • a browser-only impersonation flag;
  • dual PHP and Next.js session authorities;
  • password/session security changes under this documentation wave;
  • automatic MFA/library/vendor selection;
  • a generic permission engine inside the identity service.

2. Domain Vocabulary

Term Meaning
Physical Actor user, super-admin, system or integration that initiated the request
Effective Subject user represented by the actor; equal to actor for direct user requests, optional under impersonation
Tenant Target local/global tenant identity owning the business data
Session authenticated continuity record/token controlled by one session authority
Impersonation explicit delegated actor→subject or actor→tenant context
Reauthentication recent credential/MFA proof for one privileged action
Service Identity non-human system/integration principal explicitly bound to tenant and source
Session Bridge migration adapter allowing PHP and Next.js to consume one session authority
Revocation authoritative invalidation of a session or session family

3. Target Actor Context

interface ActorContext {
  actor: {
    type: 'USER' | 'SUPER_ADMIN' | 'SYSTEM' | 'INTEGRATION'
    id: string
    username?: string
  }
  subject: null | {
    type: 'USER'
    id: string
    username: string
  }
  tenant: {
    localTenantId: number
    globalTenantId?: string
    provenance:
      | 'SESSION'
      | 'IMPERSONATION_TARGET'
      | 'ADMIN_ROUTE_OVERRIDE'
      | 'EXPLICIT_JOB'
      | 'INTEGRATION_BINDING'
  }
  session: null | {
    sessionId: string
    issuedAt: string
    lastActivityAt?: string
    absoluteExpiresAt: string
    idleExpiresAt?: string
    authenticationTime: string
    revocationVersion?: number
  }
  impersonation: null | {
    impersonationId: string
    startedAt: string
    expiresAt: string
    reasonRef: string
    mode: 'USER' | 'TENANT_ONLY'
  }
  requestId: string
  authorizationRef?: string
  policyState: 'STRICT' | 'COMPATIBILITY_ONLY'
}

The exact persistence and transport can differ. The semantic fields may not.

3.1 Safe client projection

React may receive:

  • display username/name;
  • effective tenant display name;
  • impersonation active flag and target display;
  • session expiry/reconnect state where accepted;
  • available identity actions.

React must not receive:

  • password hash;
  • raw session token;
  • credential secret;
  • unrestricted authorization trace;
  • other-tenant identity details;
  • provider token.

4. Session State Model

ANONYMOUS
AUTHENTICATED
IMPERSONATING
REAUTH_REQUIRED
EXPIRED
REVOKED
UNKNOWN

4.1 State meanings

State Meaning Allowed behavior
ANONYMOUS no accepted session public routes only
AUTHENTICATED accepted direct session normal authorization pipeline
IMPERSONATING accepted actor/subject or actor/tenant delegation only permitted delegated actions
REAUTH_REQUIRED session exists but privileged proof is stale/missing read or non-privileged behavior only as policy permits
EXPIRED idle/absolute expiry reached reject and require sign-in
REVOKED authoritative revocation/version mismatch reject and clear local continuity
UNKNOWN authority cannot determine state consequential action denied; safe recovery/readback

4.2 Current-to-target mapping

Current evidence Target semantic state
no login_username ANONYMOUS
session login fields, no impersonation AUTHENTICATED
valid IMPERSONATE object IMPERSONATING
missing PHP session due expiry EXPIRED or ANONYMOUS; exact reason currently unavailable
invalid actor/subject/tenant relationship UNKNOWN or rejected IMPERSONATION_INVALID

5. Semantic Queries

5.1 GetCurrentIdentityContext

Returns safe physical actor, effective subject, tenant provenance, session state and impersonation metadata.

Must not mutate activity unless the selected session policy explicitly treats the query as activity.

5.2 GetCurrentSessionState

Returns:

  • state;
  • issued/authentication/last-activity/expiry timestamps when available;
  • current/other-session support availability;
  • reauthentication requirement;
  • revocation reason category without sensitive detail.

5.3 GetImpersonationState

Returns:

  • active/inactive;
  • mode;
  • target tenant;
  • safe subject display when present;
  • started/expires time;
  • actor display;
  • available end action;
  • prohibited-action summary.

5.4 GetUserSessionInventory

Optional future query. If Product does not require user-visible multi-session management, keep it administrator/support-only.

5.5 GetIdentityCommandResultByRequestToken

Used only if a command can return unknown after commit. Returns the original command result without replay.

6. Semantic Commands

6.1 AuthenticateUser

Input:

username
password
optional tenant/login realm only if accepted by Product
request/correlation ID

Required behavior:

  • normalize username without changing accepted identity semantics;
  • locate one unambiguous active identity;
  • verify modern or legacy password;
  • perform conditional hash upgrade;
  • issue/rotate one session;
  • return safe actor/session/landing result;
  • record safe success/failure evidence;
  • never reveal whether a specific username exists beyond accepted UX policy.

6.2 ChangeOwnPassword

Required inputs:

  • physical actor session;
  • effective subject policy check;
  • current password or accepted reauthentication proof;
  • new password;
  • request token if unknown-result replay is possible.

Required output:

  • password changed/not changed;
  • session rotation disposition;
  • other-session revocation disposition;
  • impersonation disposition;
  • exact current-session state.

6.3 ResetUserPassword

Required:

  • privileged actor/capability;
  • target tenant/user;
  • reason/authorization reference;
  • reauthentication policy;
  • new credential or secure reset initiation;
  • session-revocation disposition;
  • notification disposition if accepted.

6.4 StartImpersonation

Input:

target tenant
target user optional
mode USER or TENANT_ONLY
reason/authorization reference
expected current session identity
request token

Required checks:

  • physical actor is permitted;
  • target tenant exists;
  • target user belongs to tenant when selected;
  • no conflicting active impersonation;
  • selected action categories are compatible;
  • current session is recent/reauthenticated as policy requires.

Required result:

  • durable or authoritative impersonation reference;
  • actor/subject/tenant context;
  • expiry;
  • visible banner contract;
  • session-rotation result;
  • audit/correlation result.

6.5 EndImpersonation

Required result:

  • physical actor restored;
  • target subject/tenant removed;
  • session rotated when policy requires;
  • caches invalidated;
  • end audit recorded;
  • next safe landing.

6.6 InvalidateSession

Invalidates one current or selected session through the authoritative session owner.

6.7 InvalidateUserSessions

Optional command for password reset, role/tenant removal, incident response or explicit user action. Policy must state whether the current session is included.

6.8 ReauthenticatePrivilegedAction

Produces short-lived proof bound to:

  • actor;
  • session;
  • action category;
  • tenant scope;
  • issue/expiry time.

6.9 IssueServiceIdentity

Creates no browser session. Returns an explicit strict context for one job/callback/request lineage.

7. Stable Error Contract

IDENTITY_UNAUTHENTICATED
IDENTITY_INVALID_CREDENTIALS
IDENTITY_AMBIGUOUS_USERNAME
IDENTITY_ACCOUNT_DISABLED
IDENTITY_SESSION_REQUIRED
IDENTITY_SESSION_EXPIRED
IDENTITY_SESSION_REVOKED
IDENTITY_SESSION_INVALID
IDENTITY_REAUTH_REQUIRED
IDENTITY_PASSWORD_POLICY_FAILED
IDENTITY_PASSWORD_CHANGED_CONCURRENTLY
IDENTITY_IMPERSONATION_FORBIDDEN
IDENTITY_IMPERSONATION_INVALID
IDENTITY_IMPERSONATION_ALREADY_ACTIVE
IDENTITY_TARGET_TENANT_NOT_FOUND
IDENTITY_TARGET_USER_NOT_FOUND
IDENTITY_ACTOR_SUBJECT_MISMATCH
IDENTITY_ADMIN_OVERRIDE_FORBIDDEN
IDENTITY_SERVICE_BINDING_REQUIRED
IDENTITY_SERVICE_BINDING_INVALID
IDENTITY_REQUEST_DUPLICATE
IDENTITY_RESULT_UNKNOWN
IDENTITY_UNEXPECTED_ERROR

Client messages remain safe and actionable. SQL, hash, token, cookie and provider details stay in protected diagnostics.

8. Policy Decision Matrix

ID Decision Current evidence Recommended target Status
IDN-POL-010 Username namespace username-only login query prove global uniqueness or add explicit login realm OPEN
IDN-POL-020 Password minimum/complexity min 6 on change/reset; login accepts stored credentials define accepted policy without blocking migration unexpectedly OPEN
IDN-POL-030 Legacy hash retirement transparent rehash exists inventory remaining hashes; retire verifier only at zero OPEN
IDN-POL-040 Session idle timeout not explicit separate from absolute timeout if Product accepts OPEN
IDN-POL-050 Absolute timeout current 20h cookie/GC select after field impact review OPEN
IDN-POL-060 Trusted proxy forwarded proto accepted deployment allowlist/config contract OPEN
IDN-POL-070 Session revocation not established authoritative version/store before cross-runtime migration OPEN
IDN-POL-080 Password-change revocation not established explicit current/other-session disposition OPEN
IDN-POL-090 Login throttling/lockout not established separate safety decision; avoid user outage OPEN
IDN-POL-100 MFA not established privileged/admin scope first if accepted OPEN
IDN-POL-110 Impersonation reason not required in current session object required authorization reference for target design RECOMMENDED
IDN-POL-120 Impersonation expiry current PHP session lifetime explicit shorter expiry OPEN
IDN-POL-130 Session rotation at impersonation boundaries not visible rotate while preserving actor continuity RECOMMENDED / EVIDENCE REQUIRED
IDN-POL-140 Prohibited impersonation actions caller-specific explicit action categories OPEN
IDN-POL-150 Tenant-only impersonation current support exists preserve as support mode, never target-role proof RECOMMENDED
IDN-POL-160 Privileged reauthentication not established require for password reset/impersonation/secret changes if accepted OPEN
IDN-POL-170 Logout transport current GET page action target explicit state-changing command RECOMMENDED / HELD
IDN-POL-180 PHP/Next.js session authority not established one authority, adapters on both runtimes REQUIRED BEFORE P12
IDN-POL-190 Auth library/provider none selected decide only during activated architecture/implementation review DEFERRED

9. Target Component Architecture

flowchart TB
    React[React Identity UI]
    Next[Next.js Auth / Request Adapters]
    PHP[Legacy PHP Session Adapter]
    App[TypeScript Identity Application]
    Policy[Identity / Impersonation Policy]
    Repo[Session + User Repositories]
    MySQL[(MySQL)]
    Audit[Audit / Correlation]
    Provider[Optional External IdP]

    React --> Next
    Next --> App
    PHP --> App
    App --> Policy
    App --> Repo
    Repo --> MySQL
    App --> Audit
    Provider -. accepted later .-> App

Rules:

  • React never verifies passwords or decides impersonation authorization.
  • Next.js does not own identity data by embedding it in page code.
  • PHP and Next.js do not issue independent parallel sessions for the same cohort.
  • Session repository is explicit and independently testable.
  • Optional external IdP does not replace local tenant/action authorization.

10. PHP And Next.js Coexistence

10.1 Allowed patterns

Pattern A — Existing PHP session remains authority initially

Browser cookie
-> Next.js trusted bridge validates existing PHP session
-> typed Actor/Tenant context
-> no second login/session issuance

Pattern B — New shared session authority with PHP adapter

Browser cookie/token
-> shared session authority
-> Next.js adapter
-> PHP adapter

Pattern B is the eventual cleaner target but requires explicit implementation and rollback.

10.2 Prohibited pattern

PHP session valid
+ independent Next.js session valid
+ different expiry/revocation/actor/tenant state

10.3 Cutover cohort

Choose one bounded cohort, such as:

  • read-only reference page;
  • selected administrator diagnostics;
  • one non-critical tenant/role;
  • explicit internal test users.

Do not cut over all live users merely because the React UI is ready.

11. Migration Waves

IDN-W0  Current session/role/impersonation/caller/data characterization
IDN-W1  Typed read-only identity/session diagnostics
IDN-W2  Actor/subject/tenant propagation parity
IDN-W3  Session issuance/revocation authority design
IDN-W4  One PHP/Next.js read-only coexistence cohort
IDN-W5  Privileged reauthentication and impersonation semantics
IDN-W6  One authoritative login/session cohort
IDN-W7  Password change/reset and revocation parity
IDN-W8  Service/integration identity migration
IDN-W9  Target-role and cross-device stabilization
IDN-W10 Current Wiki/admin support publication
IDN-W11 Legacy scalar/session caller-zero
IDN-W12 Legacy hash verifier retirement after data zero
IDN-W13 PostgreSQL later

No wave is activated by this document.

12. Rollback

Rollback must preserve:

  • current valid sessions unless explicitly revoked for safety;
  • actor/subject/audit lineage;
  • password hashes;
  • accepted impersonation state or explicit termination evidence;
  • request/result identity;
  • current PHP login ability.

Rollback does not mean:

  • issuing a second session silently;
  • restoring an already-revoked token;
  • deleting impersonation audit;
  • copying password hashes between incompatible stores;
  • reverting a password change without user authorization;
  • running both session authorities indefinitely.

13. Stable Acceptance Scenarios

Authentication

IDN-SCN-010 modern password login
IDN-SCN-020 legacy password login and one-time rehash
IDN-SCN-030 invalid credential without identity disclosure
IDN-SCN-040 duplicate username/realm ambiguity
IDN-SCN-050 concurrent password rehash/change
IDN-SCN-060 disabled/deleted user

Session

IDN-SCN-110 session regeneration at login
IDN-SCN-120 idle timeout
IDN-SCN-130 absolute timeout
IDN-SCN-140 revoked session
IDN-SCN-150 current-session logout
IDN-SCN-160 other-session invalidation
IDN-SCN-170 role change while session active
IDN-SCN-180 password change/reset session disposition

Impersonation

IDN-SCN-210 start user impersonation
IDN-SCN-220 start tenant-only impersonation
IDN-SCN-230 target user foreign/missing
IDN-SCN-240 actor/session mismatch
IDN-SCN-250 concurrent/duplicate start
IDN-SCN-260 end impersonation and restore actor
IDN-SCN-270 expired impersonation
IDN-SCN-280 prohibited privileged action
IDN-SCN-290 target-role UI cannot be claimed from tenant-only mode

Service and migration

IDN-SCN-310 explicit CLI tenant identity
IDN-SCN-320 integration credential owner mismatch
IDN-MIG-SCN-010 PHP/Next.js identity read parity
IDN-MIG-SCN-020 single session-authority cutover
IDN-MIG-SCN-030 rollback without duplicate session
IDN-MIG-SCN-040 cross-runtime logout/revocation
IDN-MIG-SCN-050 legacy scalar caller-zero
IDN-MIG-SCN-060 PostgreSQL identity/session parity

Each scenario records exact ref, environment, actor, subject, tenant, session/request reference, expected result, authoritative reread and cleanup.

14. Definition Of Ready For Implementation Review

  • username namespace policy is known for the selected cohort;
  • current session/cookie/proxy behavior is measured;
  • actor/subject/tenant contract is accepted;
  • impersonation modes and prohibited actions are explicit;
  • one session-authority/coexistence design is selected;
  • session expiry/revocation semantics required by the wave are defined;
  • password change/reset session disposition is explicit;
  • rollback does not require dual authority;
  • target-role and Client 1 non-regression scenarios exist;
  • remaining unknowns do not change integrity or live access for the selected wave.

15. Definition Of Complete

A selected identity/session migration wave is complete only after:

  • implementation and schema are accepted;
  • local and target-role scenarios pass;
  • PHP/Next.js use one authoritative decision for the cohort;
  • actor/subject/tenant/audit readback is exact;
  • logout/expiry/revocation work across selected runtimes;
  • impersonation start/end and privileged boundaries are verified;
  • rollback is rehearsed;
  • current Wiki/admin support content is published and read back;
  • old callers reach zero for the selected scope;
  • observation/stabilization period passes.

Documentation alone does not satisfy these criteria.

---

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