Enterprise agent platform for building, deploying, and operating AI teammates.
export const AUTH_CACHE_KEY = "auth_cache"
export const AUTH_LOGIN_INTENT_KEY = "auth_login_intent"
export const AUTH_REVOKED_LOGIN_INTENT_KEY = "auth_revoked_login_intent"
export const AUTH_OIDC_INTENT_KEY = "auth_oidc_intent"
export const AUTH_TOKEN_UPDATED_EVENT = "auth-token-updated"
export const LEGACY_AUTH_TOKEN_KEY = "auth_token"
export const LEGACY_AUTH_USER_KEY = "auth_user"
export const AUTH_CACHE_DURATION_MS = 120 * 60 * 1000
const AUTH_CACHE_SCHEMA_VERSION = 2
const AUTH_LOGIN_INTENT_SCHEMA_VERSION = 1
const AUTH_MUTATION_LOCK = "xagent-auth-cache"
const MAX_REVISION = Number.MAX_SAFE_INTEGER
export interface AuthUser { id: string | number; username: string; email?: string | null; first_name?: string | null; is_admin?: boolean; has_password?: boolean }
export interface AuthCacheUser { id: string; username: string; email?: string | null; first_name?: string | null; is_admin?: boolean; has_password?: boolean }
export interface AuthTokenPayload {
user: AuthUser
access_token: string
refresh_token?: string
expires_in?: number
refresh_expires_in?: number
}
export interface AuthCache {
schemaVersion: typeof AUTH_CACHE_SCHEMA_VERSION
sessionId: string
credentialRevision: number
profileRevision: number
user: AuthCacheUser
token: string
refreshToken: string | null
timestamp: number
expiresAt?: number
refreshExpiresAt?: number
}
export interface AuthSessionSnapshot {
sessionId: string | null
credentialRevision: number | null
profileRevision: number | null
userId: string | null
accessToken: string | null
refreshToken: string | null
profileFingerprint: string | null
}
export interface AuthSessionProjection { cache: AuthCache; snapshot: AuthSessionSnapshot }
/** A short-lived capability that authorizes one password or OIDC response to create a bearer session. */
export interface AuthLoginIntent { id: string }
interface PersistedAuthLoginIntent extends AuthLoginIntent { schemaVersion: typeof AUTH_LOGIN_INTENT_SCHEMA_VERSION }
export type AuthSessionInspection =
| { status: "valid"; projection: AuthSessionProjection }
| { status: "absent" | "expired" | "invalid"; projection: null }
export type AuthSessionComparison =
| { status: "exact" | "profile_advanced" | "credentials_advanced" | "credentials_and_profile_advanced"; projection: AuthSessionProjection }
| { status: "replaced" | "absent" | "expired" | "invalid"; projection: null }
export type AuthCredentialComparison =
| { status: "exact_credentials"; projection: AuthSessionProjection }
| { status: "credentials_advanced"; projection: AuthSessionProjection }
| { status: "replaced" | "absent" | "expired" | "invalid"; projection: null }
export type AuthMutationUnavailableReason = "storage_unavailable" | "coordination_unavailable" | "operation_failed"
export type AuthStorageAvailability =
| { status: "available" }
| { status: "unavailable"; reason: "storage_unavailable" }
export type AuthMutationResult =
| { status: "created" | "migrated" | "updated" | "advanced"; projection: AuthSessionProjection }
| { status: "replaced" | "absent" | "expired" | "invalid" | "superseded" }
| { status: "unavailable"; reason: AuthMutationUnavailableReason }
export type AuthConditionalClearResult =
| { status: "cleared" | "not_current" }
| { status: "unavailable"; reason: AuthMutationUnavailableReason }
export type AuthLogoutResult =
| { status: "cleared"; credentialsCleared: true; barrier: "installed" | "removed" | "revoked" }
| { status: "unavailable"; reason: Exclude<AuthMutationUnavailableReason, "coordination_unavailable">; credentialsCleared: boolean; barrier: "installed" | "removed" | "revoked" | "unavailable" }
export type AuthIntentClaimResult =
| { status: "claimed"; intent: AuthLoginIntent }
| { status: "unavailable"; reason: AuthMutationUnavailableReason }
export type AuthOidcIntentResult =
| { status: "present"; intent: AuthLoginIntent }
| { status: "absent" }
| { status: "unavailable"; reason: Exclude<AuthMutationUnavailableReason, "coordination_unavailable"> }
type AuthStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">
type AuthSessionStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">
const AUTH_OWNED_LOCAL_STORAGE_KEYS = [
AUTH_CACHE_KEY,
AUTH_LOGIN_INTENT_KEY,
AUTH_REVOKED_LOGIN_INTENT_KEY,
LEGACY_AUTH_TOKEN_KEY,
LEGACY_AUTH_USER_KEY,
] as const
const EMPTY_SNAPSHOT: AuthSessionSnapshot = {
sessionId: null, credentialRevision: null, profileRevision: null,
userId: null, accessToken: null, refreshToken: null,
profileFingerprint: null,
}
/** The single capability boundary for browser-owned auth persistence. */
function getAuthStorage(): AuthStorage | null {
if (typeof window === "undefined") return null
try {
const storage: unknown = window.localStorage
if (typeof storage !== "object" || storage === null) return null
const candidate = storage as Partial<AuthStorage>
if (!(typeof candidate.getItem === "function"
&& typeof candidate.setItem === "function"
&& typeof candidate.removeItem === "function"
)) return null
candidate.getItem(AUTH_CACHE_KEY)
return candidate as AuthStorage
} catch {
return null
}
}
export function getAuthStorageAvailability(): AuthStorageAvailability {
return getAuthStorage() ? { status: "available" } : { status: "unavailable", reason: "storage_unavailable" }
}
function getSessionStorage(): AuthSessionStorage | null {
if (typeof window === "undefined") return null
try {
const storage: unknown = window.sessionStorage
if (typeof storage !== "object" || storage === null) return null
const candidate = storage as Partial<AuthSessionStorage>
if (!(typeof candidate.getItem === "function" && typeof candidate.setItem === "function" && typeof candidate.removeItem === "function")) return null
candidate.getItem(AUTH_OIDC_INTENT_KEY)
return candidate as AuthSessionStorage
} catch { return null }
}
function isStrictPositiveInteger(value: unknown): value is number {
return typeof value === "number" && Number.isSafeInteger(value) && value > 0
}
function isSafeAbsoluteTimestamp(value: unknown): value is number {
return typeof value === "number" && Number.isSafeInteger(value) && value > 0
}
function isRevision(value: unknown): value is number {
return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
}
function normalizeUser(value: unknown): AuthCacheUser | null {
if (typeof value !== "object" || value === null) return null
const user = value as Partial<AuthUser>
if (!(typeof user.id === "string" || typeof user.id === "number")) return null
const id = String(user.id).trim()
if (!id || typeof user.username !== "string" || !user.username.trim()) return null
if (user.email !== undefined && user.email !== null && typeof user.email !== "string") return null
if (user.is_admin !== undefined && typeof user.is_admin !== "boolean") return null
if (user.has_password !== undefined && typeof user.has_password !== "boolean") return null
const firstName = typeof user.first_name === "string" ? user.first_name : undefined
return { id, username: user.username, email: user.email, first_name: firstName, is_admin: user.is_admin, has_password: user.has_password }
}
function normalizeToken(value: unknown): string | null {
// Signed and bearer values are opaque. Trim only to reject an all-whitespace value.
return typeof value === "string" && value.trim().length > 0 ? value : null
}
function normalizeExpiry(value: unknown): number | undefined | null {
if (value === undefined) return undefined
return isSafeAuthExpirySeconds(value) ? value : null
}
function deadlineFromSeconds(now: number, seconds: number | undefined): number | undefined | null {
if (seconds === undefined) return undefined
const milliseconds = seconds * 1000
const deadline = now + milliseconds
return Number.isFinite(milliseconds) && Number.isSafeInteger(deadline) && deadline > now ? deadline : null
}
/** Validates an expiry together with the absolute deadline auth storage will persist. */
export function isSafeAuthExpirySeconds(value: unknown, now = Date.now()): value is number {
return isStrictPositiveInteger(value) && deadlineFromSeconds(now, value) !== null
}
function createSessionId(): string {
if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID()
const bytes = new Uint32Array(4)
if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
crypto.getRandomValues(bytes)
return Array.from(bytes, value => value.toString(16).padStart(8, "0")).join("")
}
throw new Error("Secure session lineage generation is unavailable")
}
function parseAuthLoginIntent(raw: string | null): AuthLoginIntent | null {
if (raw === null) return null
try {
const value: unknown = JSON.parse(raw)
if (typeof value !== "object" || value === null) return null
const intent = value as Partial<PersistedAuthLoginIntent>
return intent.schemaVersion === AUTH_LOGIN_INTENT_SCHEMA_VERSION
&& typeof intent.id === "string" && intent.id.length > 0
? { id: intent.id }
: null
} catch { return null }
}
function serializeAuthLoginIntent(intent: AuthLoginIntent): string {
const persisted: PersistedAuthLoginIntent = { schemaVersion: AUTH_LOGIN_INTENT_SCHEMA_VERSION, ...intent }
return JSON.stringify(persisted)
}
function hasAuthLoginIntent(storage: AuthStorage, intent: AuthLoginIntent | null | undefined): boolean {
if (typeof intent?.id !== "string" || intent.id.length === 0) return false
return parseAuthLoginIntent(storage.getItem(AUTH_LOGIN_INTENT_KEY))?.id === intent.id
&& parseAuthLoginIntent(storage.getItem(AUTH_REVOKED_LOGIN_INTENT_KEY))?.id !== intent.id
}
function replaceAuthLoginIntent(storage: AuthStorage): AuthLoginIntent {
const intent = { id: createSessionId() }
storage.setItem(AUTH_LOGIN_INTENT_KEY, serializeAuthLoginIntent(intent))
return intent
}
function projectionFromCache(cache: AuthCache): AuthSessionProjection {
return { cache, snapshot: {
sessionId: cache.sessionId, credentialRevision: cache.credentialRevision,
profileRevision: cache.profileRevision, userId: cache.user.id,
accessToken: cache.token, refreshToken: cache.refreshToken,
profileFingerprint: JSON.stringify([cache.user.username, cache.user.email ?? null, cache.user.is_admin ?? null]),
} }
}
function cacheUsable(cache: AuthCache, now: number): boolean {
return cache.refreshToken && cache.refreshExpiresAt !== undefined
? cache.refreshExpiresAt > now
: now - cache.timestamp <= AUTH_CACHE_DURATION_MS
}
export function isAuthCacheUsable(cache: AuthCache, now = Date.now()): boolean { return cacheUsable(cache, now) }
export function parseAuthTokenPayload(value: unknown): AuthTokenPayload | null {
if (typeof value !== "object" || value === null) return null
const data = value as Partial<AuthTokenPayload>
const user = normalizeUser(data.user)
const accessToken = normalizeToken(data.access_token)
const refresh = data.refresh_token === undefined ? undefined : normalizeToken(data.refresh_token)
const expiresIn = normalizeExpiry(data.expires_in)
const refreshExpiresIn = normalizeExpiry(data.refresh_expires_in)
if (!user || !accessToken || refresh === null || expiresIn === null || refreshExpiresIn === null) return null
return { user, access_token: accessToken, refresh_token: refresh, expires_in: expiresIn, refresh_expires_in: refreshExpiresIn }
}
function parseRefreshCommitPayload(value: unknown): Omit<AuthTokenPayload, "user"> | null {
if (typeof value !== "object" || value === null) return null
const data = value as Partial<Omit<AuthTokenPayload, "user">> & { success?: unknown }
if (data.success !== true) return null
const accessToken = normalizeToken(data.access_token)
const refresh = normalizeToken(data.refresh_token)
const expiresIn = normalizeExpiry(data.expires_in)
const refreshExpiresIn = normalizeExpiry(data.refresh_expires_in)
if (!accessToken || !refresh || expiresIn === null || refreshExpiresIn === null) return null
return { access_token: accessToken, refresh_token: refresh, expires_in: expiresIn, refresh_expires_in: refreshExpiresIn }
}
function parseCanonical(raw: string): AuthCache | null {
try {
const value: unknown = JSON.parse(raw)
if (typeof value !== "object" || value === null) return null
const cache = value as Partial<AuthCache>
const user = normalizeUser(cache.user)
if (cache.schemaVersion !== AUTH_CACHE_SCHEMA_VERSION || typeof cache.sessionId !== "string" || !cache.sessionId
|| !isRevision(cache.credentialRevision) || !isRevision(cache.profileRevision)
|| !user || !normalizeToken(cache.token) || !isSafeAbsoluteTimestamp(cache.timestamp)) return null
if (cache.expiresAt !== undefined && !isSafeAbsoluteTimestamp(cache.expiresAt)) return null
if (cache.refreshExpiresAt !== undefined && !isSafeAbsoluteTimestamp(cache.refreshExpiresAt)) return null
if (cache.refreshToken !== null && cache.refreshToken !== undefined && !normalizeToken(cache.refreshToken)) return null
return {
schemaVersion: AUTH_CACHE_SCHEMA_VERSION, sessionId: cache.sessionId,
credentialRevision: cache.credentialRevision, profileRevision: cache.profileRevision,
user, token: cache.token!, refreshToken: cache.refreshToken || null,
timestamp: cache.timestamp, expiresAt: cache.expiresAt, refreshExpiresAt: cache.refreshExpiresAt,
}
} catch { return null }
}
type LegacyCanonicalInspection =
| { status: "valid"; cache: Omit<AuthCache, "schemaVersion" | "sessionId" | "credentialRevision" | "profileRevision"> }
| { status: "expired" | "invalid" }
/** Recognize only the exact pre-v2 canonical cache shape; it is never a shadow fallback. */
function inspectLegacyCanonical(raw: string, now: number): LegacyCanonicalInspection {
try {
const value: unknown = JSON.parse(raw)
if (typeof value !== "object" || value === null) return { status: "invalid" }
const cache = value as Partial<AuthCache>
if (cache.schemaVersion !== undefined || cache.sessionId !== undefined
|| cache.credentialRevision !== undefined || cache.profileRevision !== undefined) return { status: "invalid" }
const user = normalizeUser(cache.user)
const token = normalizeToken(cache.token)
if (!user || !token || !isSafeAbsoluteTimestamp(cache.timestamp)) return { status: "invalid" }
if (cache.expiresAt !== undefined && !isSafeAbsoluteTimestamp(cache.expiresAt)) return { status: "invalid" }
if (cache.refreshExpiresAt !== undefined && !isSafeAbsoluteTimestamp(cache.refreshExpiresAt)) return { status: "invalid" }
if (cache.refreshToken !== null && cache.refreshToken !== undefined && !normalizeToken(cache.refreshToken)) return { status: "invalid" }
const legacy = {
user, token, refreshToken: cache.refreshToken || null, timestamp: cache.timestamp,
expiresAt: cache.expiresAt, refreshExpiresAt: cache.refreshExpiresAt,
}
const usable = legacy.refreshToken && legacy.refreshExpiresAt !== undefined
? legacy.refreshExpiresAt > now
: now - legacy.timestamp <= AUTH_CACHE_DURATION_MS
return usable ? { status: "valid", cache: legacy } : { status: "expired" }
} catch { return { status: "invalid" } }
}
/** Pure storage inspection. It never evicts or migrates. */
export function inspectAuthSession(now = Date.now()): AuthSessionInspection {
const storage = getAuthStorage()
if (!storage) return { status: "absent", projection: null }
let raw: string | null
try {
raw = storage.getItem(AUTH_CACHE_KEY)
} catch {
return { status: "absent", projection: null }
}
if (raw === null) return { status: "absent", projection: null }
const cache = parseCanonical(raw)
if (!cache) return { status: "invalid", projection: null }
if (!cacheUsable(cache, now)) return { status: "expired", projection: null }
return { status: "valid", projection: projectionFromCache(cache) }
}
export function readAuthCache(now = Date.now()): AuthCache | null {
const inspection = inspectAuthSession(now)
return inspection.status === "valid" ? inspection.projection.cache : null
}
export function readAuthSessionSnapshot(): AuthSessionSnapshot {
const inspection = inspectAuthSession()
return inspection.status === "valid" ? inspection.projection.snapshot : EMPTY_SNAPSHOT
}
export type AuthSessionLineage = "same" | "replaced" | "invalid"
/** Compare two snapshots without touching shared storage. */
export function compareAuthSessionLineage(captured: AuthSessionSnapshot, current: AuthSessionSnapshot): AuthSessionLineage {
if (!captured.sessionId || current.sessionId !== captured.sessionId) return "replaced"
if (current.userId !== captured.userId || current.credentialRevision === null || current.profileRevision === null) {
return "invalid"
}
if (current.credentialRevision < (captured.credentialRevision ?? -1) || current.profileRevision < (captured.profileRevision ?? -1)) {
return "invalid"
}
if (current.credentialRevision === captured.credentialRevision && (current.accessToken !== captured.accessToken || current.refreshToken !== captured.refreshToken)) {
return "invalid"
}
if (current.profileRevision === captured.profileRevision && current.profileFingerprint !== captured.profileFingerprint) {
return "invalid"
}
return "same"
}
export function compareAuthSession(captured: AuthSessionSnapshot, inspection = inspectAuthSession()): AuthSessionComparison {
if (inspection.status !== "valid") return { status: inspection.status, projection: null }
const { cache, snapshot } = inspection.projection
const lineage = compareAuthSessionLineage(captured, snapshot)
if (lineage === "replaced") return { status: "replaced", projection: null }
if (lineage === "invalid") return { status: "invalid", projection: null }
const credentialExact = cache.credentialRevision === captured.credentialRevision && cache.token === captured.accessToken && cache.refreshToken === captured.refreshToken
const profileExact = cache.profileRevision === captured.profileRevision
if (credentialExact && profileExact) return { status: "exact", projection: inspection.projection }
if (credentialExact) return { status: "profile_advanced", projection: inspection.projection }
if (profileExact) return { status: "credentials_advanced", projection: inspection.projection }
return { status: "credentials_and_profile_advanced", projection: inspection.projection }
}
export function compareCredentialSession(captured: AuthSessionSnapshot, inspection = inspectAuthSession()): AuthCredentialComparison {
const comparison = compareAuthSession(captured, inspection)
if (comparison.status === "exact" || comparison.status === "profile_advanced") {
return { status: "exact_credentials", projection: comparison.projection }
}
if (comparison.status === "credentials_advanced" || comparison.status === "credentials_and_profile_advanced") {
return { status: "credentials_advanced", projection: comparison.projection }
}
return { status: comparison.status, projection: null }
}
function isExactCredential(c: AuthCredentialComparison): boolean { return c.status === "exact_credentials" }
function isCredentialAdvanced(c: AuthCredentialComparison): boolean { return c.status === "credentials_advanced" }
function dispatchAuthTokenUpdated() {
if (typeof window === "undefined" || typeof window.dispatchEvent !== "function") return
try {
window.dispatchEvent(new Event(AUTH_TOKEN_UPDATED_EVENT))
} catch {
// Storage persistence owns correctness; cross-context notification is best effort.
}
}
function snapshotAuthStorage(storage: AuthStorage): Map<string, string | null> {
return new Map(AUTH_OWNED_LOCAL_STORAGE_KEYS.map(key => [key, storage.getItem(key)]))
}
function restoreStorageValue(storage: AuthStorage | AuthSessionStorage, key: string, value: string | null): boolean {
try {
if (storage.getItem(key) === value) return true
if (value === null) storage.removeItem(key)
else storage.setItem(key, value)
return true
} catch {
return false
}
}
function restoreAuthStorage(storage: AuthStorage, snapshot: ReadonlyMap<string, string | null>): boolean {
let restored = true
for (const [key, value] of snapshot) {
if (!restoreStorageValue(storage, key, value)) restored = false
}
return restored
}
function restoreSessionValue(storage: AuthSessionStorage, key: string, value: string | null): boolean {
return restoreStorageValue(storage, key, value)
}
type AuthMutationContext = {
storage: AuthStorage
markAuthUpdated: () => void
}
function persist(storage: AuthStorage, cache: AuthCache, markAuthUpdated: () => void) {
storage.setItem(AUTH_CACHE_KEY, JSON.stringify(cache))
markAuthUpdated()
}
function writeNewSession(storage: AuthStorage, payload: AuthTokenPayload, markAuthUpdated: () => void): AuthSessionProjection {
const now = Date.now()
const expiresAt = deadlineFromSeconds(now, payload.expires_in)
const refreshExpiresAt = deadlineFromSeconds(now, payload.refresh_expires_in)
if (expiresAt === null || refreshExpiresAt === null) throw new Error("Unsafe token expiry")
const cache: AuthCache = {
schemaVersion: AUTH_CACHE_SCHEMA_VERSION, sessionId: createSessionId(), credentialRevision: 0, profileRevision: 0,
user: payload.user as AuthCacheUser, token: payload.access_token, refreshToken: payload.refresh_token || null,
timestamp: now, expiresAt, refreshExpiresAt,
}
persist(storage, cache, markAuthUpdated)
return projectionFromCache(cache)
}
type AuthMutationAttempt<T> =
| { status: "completed"; value: T }
| { status: "unavailable"; reason: AuthMutationUnavailableReason }
async function withMutationLock<T>(conditional: boolean, action: (context: AuthMutationContext) => Promise<T>): Promise<AuthMutationAttempt<T>> {
const storage = getAuthStorage()
if (!storage) return { status: "unavailable", reason: "storage_unavailable" }
const locks = typeof navigator === "undefined" ? undefined : navigator.locks
if (!locks && conditional) return { status: "unavailable", reason: "coordination_unavailable" }
let shouldDispatch = false
const run = async (): Promise<AuthMutationAttempt<T>> => {
let snapshot: Map<string, string | null> | null = null
if (conditional) {
try {
snapshot = snapshotAuthStorage(storage)
} catch {
return { status: "unavailable", reason: "storage_unavailable" }
}
}
let changed = false
const context: AuthMutationContext = {
storage,
markAuthUpdated: () => { changed = true },
}
try {
const value = await action(context)
shouldDispatch = changed
return { status: "completed", value }
} catch {
const rollbackComplete = !snapshot || restoreAuthStorage(storage, snapshot)
if (!rollbackComplete) shouldDispatch = true
return { status: "unavailable", reason: "operation_failed" }
}
}
try {
return locks ? await locks.request(AUTH_MUTATION_LOCK, run) : await run()
} catch {
return { status: "unavailable", reason: "operation_failed" }
} finally {
// A same-tab observer may synchronously read storage, so publication must
// happen only after the Web Lock callback has returned successfully.
if (shouldDispatch) dispatchAuthTokenUpdated()
}
}
function unavailable(reason: AuthMutationUnavailableReason): AuthMutationResult { return { status: "unavailable", reason } }
function nextRevision(value: number): number | null { return value < MAX_REVISION ? value + 1 : null }
/** Claims exclusive user intent before a password request or OIDC redirect begins. */
export async function claimAuthLoginIntent(): Promise<AuthIntentClaimResult> {
const result = await withMutationLock(true, async ({ storage }) => {
const intent = replaceAuthLoginIntent(storage)
// Tombstones fence only their exact old capability. A later claim has a
// distinct id, so failure to prune an old tombstone cannot invalidate it.
try { storage.removeItem(AUTH_REVOKED_LOGIN_INTENT_KEY) } catch { /* stale tombstone remains safely scoped */ }
return { status: "claimed" as const, intent }
})
return result.status === "completed" ? result.value : result
}
/** Claims an intent and binds it to this tab before an OIDC full-page redirect. */
export async function claimOidcAuthLoginIntent(): Promise<AuthIntentClaimResult> {
const sessionStorage = getSessionStorage()
if (!sessionStorage) return { status: "unavailable", reason: "storage_unavailable" }
const result = await withMutationLock(true, async ({ storage }) => {
const previousSessionIntent = sessionStorage.getItem(AUTH_OIDC_INTENT_KEY)
const intent = replaceAuthLoginIntent(storage)
try {
sessionStorage.setItem(AUTH_OIDC_INTENT_KEY, serializeAuthLoginIntent(intent))
} catch {
try { restoreSessionValue(sessionStorage, AUTH_OIDC_INTENT_KEY, previousSessionIntent) } catch { /* The failed session-storage owner remains unavailable. */ }
throw new Error("OIDC intent binding failed")
}
// Tombstones fence only their exact old capability. A later claim has a
// distinct id, so failure to prune an old tombstone cannot invalidate it.
try { storage.removeItem(AUTH_REVOKED_LOGIN_INTENT_KEY) } catch { /* stale tombstone remains safely scoped */ }
return { status: "claimed" as const, intent }
})
return result.status === "completed" ? result.value : result
}
/** Takes the OIDC intent created in this tab; callbacks cannot adopt a later intent. */
export function takeOidcAuthLoginIntent(): AuthOidcIntentResult {
const storage = getSessionStorage()
if (!storage) return { status: "unavailable", reason: "storage_unavailable" }
try {
const raw = storage.getItem(AUTH_OIDC_INTENT_KEY)
if (raw === null) return { status: "absent" }
const intent = parseAuthLoginIntent(raw)
storage.removeItem(AUTH_OIDC_INTENT_KEY)
return intent ? { status: "present", intent } : { status: "absent" }
} catch { return { status: "unavailable", reason: "operation_failed" } }
}
/** Password/OIDC session creation validates its originating intent under the same lock as the write. */
export async function createAuthSession(value: unknown, intent?: AuthLoginIntent | null): Promise<AuthMutationResult> {
const payload = parseAuthTokenPayload(value)
if (!payload) return { status: "invalid" }
const result = await withMutationLock(true, async ({ storage, markAuthUpdated }) => {
if (!intent || !hasAuthLoginIntent(storage, intent)) return { status: "superseded" as const }
// Consume this one-shot capability before persisting its bearer response.
replaceAuthLoginIntent(storage)
return { status: "created" as const, projection: writeNewSession(storage, payload, markAuthUpdated) }
})
return result.status === "completed" ? result.value : unavailable(result.reason)
}
/** Legacy migration is conditional: no lock means no unsafe migration. */
export async function migrateLegacyAuthSession(): Promise<AuthMutationResult> {
const result = await withMutationLock(true, async ({ storage, markAuthUpdated }) => {
const canonicalRaw = storage.getItem(AUTH_CACHE_KEY)
if (canonicalRaw !== null) {
const canonical = parseCanonical(canonicalRaw)
if (canonical) {
if (!cacheUsable(canonical, Date.now())) return { status: "expired" as const }
return { status: "advanced" as const, projection: projectionFromCache(canonical) }
}
const legacyCanonical = inspectLegacyCanonical(canonicalRaw, Date.now())
if (legacyCanonical.status !== "valid") return { status: legacyCanonical.status }
const migrated: AuthCache = {
schemaVersion: AUTH_CACHE_SCHEMA_VERSION, sessionId: createSessionId(), credentialRevision: 0, profileRevision: 0,
...legacyCanonical.cache,
}
persist(storage, migrated, markAuthUpdated)
storage.removeItem(LEGACY_AUTH_TOKEN_KEY); storage.removeItem(LEGACY_AUTH_USER_KEY)
return { status: "migrated" as const, projection: projectionFromCache(migrated) }
}
const token = storage.getItem(LEGACY_AUTH_TOKEN_KEY)
const rawUser = storage.getItem(LEGACY_AUTH_USER_KEY)
if (!token || !rawUser) return { status: "absent" as const }
let user: unknown
try { user = JSON.parse(rawUser) } catch { return { status: "invalid" as const } }
const payload = parseAuthTokenPayload({ user, access_token: token })
if (!payload) return { status: "invalid" as const }
const projection = writeNewSession(storage, payload, markAuthUpdated)
storage.removeItem(LEGACY_AUTH_TOKEN_KEY); storage.removeItem(LEGACY_AUTH_USER_KEY)
return { status: "migrated" as const, projection }
})
return result.status === "completed" ? result.value : unavailable(result.reason)
}
function advanceExact(storage: AuthStorage, cache: AuthCache, payload: Omit<AuthTokenPayload, "user">, markAuthUpdated: () => void): AuthMutationResult {
const revision = nextRevision(cache.credentialRevision)
if (revision === null) return { status: "invalid" }
const now = Date.now()
const expiresAt = deadlineFromSeconds(now, payload.expires_in)
const refreshExpiresAt = deadlineFromSeconds(now, payload.refresh_expires_in)
if (expiresAt === null || refreshExpiresAt === null) return { status: "invalid" }
const updated: AuthCache = {
...cache, credentialRevision: revision, token: payload.access_token,
refreshToken: payload.refresh_token!, timestamp: now,
expiresAt: expiresAt ?? cache.expiresAt,
refreshExpiresAt: refreshExpiresAt ?? cache.refreshExpiresAt,
}
persist(storage, updated, markAuthUpdated); return { status: "updated", projection: projectionFromCache(updated) }
}
/** Commits a refresh response only when the captured credential lineage is still current. */
export async function commitAuthSessionRefresh(captured: AuthSessionSnapshot, value: unknown): Promise<AuthMutationResult> {
const result = await withMutationLock(true, async ({ storage, markAuthUpdated }) => {
const comparison = compareCredentialSession(captured)
if (isCredentialAdvanced(comparison)) return { status: "advanced" as const, projection: comparison.projection! }
if (!isExactCredential(comparison)) return { status: comparison.status as "replaced" | "absent" | "expired" | "invalid" }
const payload = parseRefreshCommitPayload(value)
if (!payload) return { status: "invalid" as const }
return advanceExact(storage, comparison.projection!.cache, payload, markAuthUpdated)
})
return result.status === "completed" ? result.value : unavailable(result.reason)
}
export async function updateAuthSessionUser(captured: AuthSessionSnapshot, next: AuthUser | AuthCacheUser): Promise<AuthMutationResult> {
const user = normalizeUser(next)
if (!user || user.id !== captured.userId) return { status: "invalid" }
const result = await withMutationLock(true, async ({ storage, markAuthUpdated }) => {
const comparison = compareAuthSession(captured)
if (comparison.status === "replaced" || comparison.status === "invalid" || comparison.status === "absent" || comparison.status === "expired") return { status: comparison.status }
const cache = comparison.projection!.cache
if (cache.user.id !== user.id || cache.profileRevision !== captured.profileRevision) return { status: "advanced" as const, projection: comparison.projection! }
const revision = nextRevision(cache.profileRevision)
if (revision === null) return { status: "invalid" as const }
const updated = {
...cache,
user: {
...cache.user,
username: user.username,
email: user.email,
first_name: user.first_name ?? cache.user.first_name,
is_admin: user.is_admin,
// Keep the password-capability marker in the canonical cache. OIDC
// users have no local password, and dropping this field here makes
// the settings page require a password they cannot provide after a
// /me profile refresh.
has_password: user.has_password ?? cache.user.has_password,
},
profileRevision: revision,
}
persist(storage, updated, markAuthUpdated); return { status: "updated" as const, projection: projectionFromCache(updated) }
})
return result.status === "completed" ? result.value : unavailable(result.reason)
}
export async function clearAuthSessionIfCurrent(captured: AuthSessionSnapshot): Promise<AuthConditionalClearResult> {
const result = await withMutationLock(true, async ({ storage, markAuthUpdated }) => {
const comparison = compareCredentialSession(captured)
if (!isExactCredential(comparison)) return { status: "not_current" as const }
storage.removeItem(AUTH_CACHE_KEY); markAuthUpdated(); return { status: "cleared" as const }
})
return result.status === "completed" ? result.value : result
}
/** Explicit logout is serialized when possible, and remains available without Web Locks. */
export async function clearStoredAuth(): Promise<AuthLogoutResult> {
const result = await withMutationLock(false, async ({ storage, markAuthUpdated }) => {
let barrier: AuthLogoutResult["barrier"] = "unavailable"
let pendingIntent: AuthLoginIntent | null = null
try { pendingIntent = parseAuthLoginIntent(storage.getItem(AUTH_LOGIN_INTENT_KEY)) } catch { /* no durable intent to revoke */ }
try {
replaceAuthLoginIntent(storage)
try { storage.removeItem(AUTH_REVOKED_LOGIN_INTENT_KEY) } catch { /* a new barrier supersedes the old tombstone */ }
barrier = "installed"
} catch {
try {
storage.removeItem(AUTH_LOGIN_INTENT_KEY)
barrier = "removed"
} catch {
if (pendingIntent) {
try {
storage.setItem(AUTH_REVOKED_LOGIN_INTENT_KEY, serializeAuthLoginIntent(pendingIntent))
barrier = "revoked"
} catch {
barrier = "unavailable"
}
}
}
}
let credentialsCleared = true
try {
storage.removeItem(AUTH_CACHE_KEY)
markAuthUpdated()
} catch {
credentialsCleared = false
}
for (const key of [LEGACY_AUTH_TOKEN_KEY, LEGACY_AUTH_USER_KEY]) {
try {
storage.removeItem(key)
} catch {
credentialsCleared = false
}
}
if (credentialsCleared && barrier !== "unavailable") return { status: "cleared" as const, credentialsCleared: true as const, barrier }
return { status: "unavailable" as const, reason: "operation_failed" as const, credentialsCleared, barrier }
})
if (result.status === "completed") return result.value
return { status: "unavailable", reason: result.reason === "storage_unavailable" ? result.reason : "operation_failed", credentialsCleared: false, barrier: "unavailable" }
}