cadrumo.application.user_profile.session_admission module

The one door that admits a profile session for use, whoever is asking.

Every surface that needs an unlocked profile wants the same sequence: reuse a session this process already holds, else resume the acceleration receipt, else ask the operator for credentials, and in every case prove afterwards that the session now bound is the one that was asked for. The CLI grew that sequence inside its own dispatch gate and the installed workbench grew a second copy in its bootstrap, which is how the two surfaces came to disagree about what being logged in means.

So the sequence lives here, once, and the surfaces supply only what is genuinely theirs: how to obtain credentials from their operator. A parsed CLI invocation reads a passphrase from a declared secret channel; the installed workbench opens its existing Login screen. Neither decides what counts as an admitted session, and neither may skip the proof at the end.

The door never holds session state of its own. Binding belongs to the login services it calls, which publish process-wide through the login-session port; this module only sequences them and reports, in typed terms, what happened.

See also

bind_resumed_profile_session()

The single resume authority this door consults first.

authenticate_profile_for_invocation()

The non-selecting authentication a journey uses for one invocation.

class ProfileSessionAdmissionState(*values)[source]

Bases: StrEnum

Closed set of outcomes for one attempt to admit a profile session.

The three admitting states are kept apart rather than collapsed into a boolean because they carry different obligations. A reused or resumed session costs the operator nothing and needs no notice; an authenticated one may be process-scoped and owes them that fact.

The two refusing states are likewise distinct. CREDENTIALS_REQUIRED means nobody was available to ask – a non-interactive invocation with no secret channel – and is a refusal about the CALLER. DECLINED means the operator was asked and chose not to authenticate, which is an ordinary outcome and not an error.

ALREADY_ADMITTED

A live session in this process already served the requested profile.

RESUMED

The persisted acceleration receipt served, with no credential prompt.

AUTHENTICATED

The supplied credential journey authenticated the profile.

CREDENTIALS_REQUIRED

No session could be resumed and no credential journey was offered.

DECLINED

The credential journey ran and the operator did not authenticate.

class ProfileCredentialRequestV1(bucket_id, profile_decode_context, resume_refusal)[source]

Bases: object

What a credential journey is told before it asks the operator.

resume_refusal is passed deliberately: a journey that wants to explain WHY credentials are needed – an expired session reads differently from a never-logged-in one – has the typed reason rather than having to re-derive it, and a journey that does not care may ignore it.

Parameters:
bucket_id: str | None
profile_decode_context: ProfileDecodeContext
resume_refusal: ProfileSessionRefusalReason
class ProfileCredentialJourneyV1(*args, **kwargs)[source]

Bases: Protocol

The surface-owned half of admission: obtain credentials and authenticate.

A journey returns the login outcome it achieved, or None when the operator declined. It must authenticate through a canonical login door – authenticate_profile_for_invocation for a target scoped to one invocation, login_profile when the operator is genuinely selecting a profile – so that binding, throttling and handover stay owned by the login services rather than re-implemented per surface.

class ProfileSessionAdmissionV1(state, bucket_id, outcome=None, resume_refusal=None)[source]

Bases: object

One closed, non-secret account of an admission attempt.

Parameters:
state: ProfileSessionAdmissionState
bucket_id: str | None
outcome: ProfileLoginOutcome | None
resume_refusal: ProfileSessionRefusalReason | None
property admitted: bool

Whether a live session now serves bucket_id.

admit_profile_session(*, bucket_id, profile_decode_context, credentials=None, now=None)[source]

Reuse, resume, or authenticate bucket_id, and prove the result.

The order is fixed and is the whole point of the door. Reuse first, because a session this process already holds costs nothing and prompting over it would be a defect the operator sees as a second passphrase for one command. Resume second, because the acceleration receipt exists precisely to avoid the prompt. Credentials last, and only from the journey the caller supplied.

The proof at the end is not a formality. Every admitting branch asserts that the bound session serves this exact profile, because the failure it catches – a binding that did not survive the frame that made it, or an authentication that bound a different profile – is silent otherwise and surfaces much later as an unreadable record.

Parameters:

  • bucket_id (str | None) – The exact profile UUID to admit, already resolved – this door does not interpret labels. None when the operator has not named a profile yet, which only a credential journey can resolve.

  • profile_decode_context (ProfileDecodeContext) – The decode context of the enclosing pinned authority operation. Resuming or authenticating without one is refused by the services below; no bundled-schema fallback exists.

  • credentials (ProfileCredentialJourneyV1 | None) – The surface’s credential journey, or None for a caller that cannot prompt.

  • now (datetime | None) – UTC evaluation instant; the canonical clock when omitted.

Return type:

ProfileSessionAdmissionV1

Returns:

The typed admission account, carrying the resume refusal on every branch that had one.

Raises:

InternalInvariantError – When a branch that reports an admitted session did not leave one bound for this exact profile.