tlc.auth

Public advisory authorization API.

tlc.auth is the read-only view over the active auth handle. The actual authorization decision lives at every write call site (the native gate); advisory results may disagree with the gate (e.g. a True result that loses to a revocation-race before the write reaches the gate).

Use this module for UX surfaces — status bars, banners, log decorators. Do not use it to guard a write path — the gate makes the authoritative decision at the write itself.

tlc.auth is observation-only and exposes no activation entry points. Activation happens through the standard credential flow: 3lc login, the TLC_API_KEY environment variable, or TLC_LICENSE for Enterprise On-Prem deployments.

Module Contents

Classes

Class	Description
Identity	Snapshot of the active auth handle’s identity at the moment of capture.

Functions

Function	Description
assert_activated	Raise if the gate would currently refuse a write.
current_identity	Snapshot of the active identity, or None if no handle is installed.
expiry_status	Classify the active handle’s expiry posture.
is_activated	Whether an auth handle is installed in this process.
would_authorize	Pure advisory predicate: identity-pin holds AND not expired.

API

class Identity

Snapshot of the active auth handle’s identity at the moment of capture.

Not a live view — re-call tlc.auth.current_identity() to pick up changes from a refresh.

Variables:

• user_id – User id claimed by the active handle.

• tenant_id – Tenant id claimed by the active handle.

• auth_mode – One of "api_key", "license_key", "dev", or "test".

• provenance – One of "root" (this process activated) or "inherited" (came from a parent via fork/spawn handoff).

auth_mode: str = None

provenance: str = None

tenant_id: str = None

user_id: str = None

assert_activated() → None

Raise if the gate would currently refuse a write.

The error type and message are byte-for-byte identical to what the real gate raises — so a UX preflight failure and a gate failure are indistinguishable to log scrapers and exception handlers.

Runs the full pipeline; same side effects as the real gate.

Raises:

• RuntimeError – If no handle is installed.

• ValueError – If the handle is expired, identity has drifted, or a refresh callback returned a hard rejection.

• ConnectionError – If a refresh callback hit a transport failure the gate could not recover from.

current_identity() → Identity | None

Snapshot of the active identity, or None if no handle is installed.

The returned tlc.auth.Identity is a frozen dataclass captured at call time — it does not update if the handle is later refreshed or revoked. Re-call to pick up changes.

Reads the active handle slot directly; does not lazy-activate from the environment.

Returns:

An Identity snapshot, or None if no handle is installed.

expiry_status() → Literal[ok, near_expiry, expired, none]

Classify the active handle’s expiry posture.

Pure read of wall-clock + handle state; no refresh invocation. "near_expiry" is a hint that the next gate call will likely trigger a refresh; it does not engage that refresh itself.

Returns:

"none" if no handle is installed; otherwise one of "ok", "near_expiry", "expired".

is_activated() → bool

Whether an auth handle is installed in this process.

Pure observation — reads the active handle slot directly without triggering lazy activation from the environment.

A True result means “an activation has happened in this process,” not “the next write will succeed.” Use tlc.auth.would_authorize() or tlc.auth.assert_activated() to check whether the gate would actually pass.

Returns:

True if an auth handle is installed, False otherwise.

would_authorize() → bool

Pure advisory predicate: identity-pin holds AND not expired.

Does not invoke the refresh callback and does not touch process-global pipeline state — none of the gate’s recovery side effects fire. A near-expiry handle returns True here even though the real gate would refresh first — the predicate answers “is this handle authoritative right now”, not “would the gate accept it after running the full pipeline.”

Returns:

True if the active handle would authorize right now; False if it would not, or if no handle is installed.