feat: add ephemeral private credentials

Author: SarthakWade

README.md

@@ -185,6 +185,11 @@ No, and requires a user-entered alias. Linux vault management is available,
 but saved alias use fails closed until a trusted per-use confirmation surface
 exists.
 
+With `--session NAME` for an isolated session, interactive saves go only to an
+in-memory vault owned by that session. Private challenges list only those
+ephemeral aliases. Closing the session or terminating the host erases them;
+the durable normal vault is never queried.
+
 ## Agent skill
 
 This repository ships a portable browser-computer-use skill at

apps/headless/Sources/HeadlessProtocol/Authentication.swift

@@ -178,6 +178,71 @@ public struct UnavailableAuthenticationBroker: AuthenticationBroker {
     }
 }
 
+public final class EphemeralAuthenticationBroker: @unchecked Sendable, AuthenticationBroker {
+    public static let maximumRecords = 100
+
+    private struct Record {
+        let origin: CredentialOrigin
+        let alias: CredentialAlias
+        let account: String
+        let password: AuthenticationSecret
+    }
+
+    private let lock = NSLock()
+    private var records: [Record] = []
+
+    public init() {}
+    deinit { removeAll() }
+
+    public func aliases(for origin: CredentialOrigin) throws -> [AuthenticationAlias] {
+        try lock.withLock {
+            try records.filter { $0.origin == origin }
+                .sorted { $0.alias.rawValue < $1.alias.rawValue }
+                .map { try AuthenticationAlias(alias: $0.alias, account: $0.account) }
+        }
+    }
+
+    public func credential(
+        for origin: CredentialOrigin, alias: CredentialAlias
+    ) throws -> AuthenticationCredential {
+        try lock.withLock {
+            guard let record = records.first(where: {
+                $0.origin == origin
+                    && $0.alias.rawValue.caseInsensitiveCompare(alias.rawValue) == .orderedSame
+            }) else { throw AuthenticationError.accountNotFound }
+            return try AuthenticationCredential(
+                account: record.account,
+                password: AuthenticationSecret(record.password.withUnsafeBytes { Array($0) })
+            )
+        }
+    }
+
+    public func store(
+        _ credential: AuthenticationCredential, for origin: CredentialOrigin, alias: CredentialAlias
+    ) throws {
+        try lock.withLock {
+            guard records.count < Self.maximumRecords else {
+                throw AuthenticationError.brokerFailed("private credential limit")
+            }
+            guard !records.contains(where: {
+                $0.origin == origin
+                    && $0.alias.rawValue.caseInsensitiveCompare(alias.rawValue) == .orderedSame
+            }) else { throw AuthenticationError.credentialAliasExists }
+            records.append(Record(
+                origin: origin, alias: alias, account: credential.account,
+                password: AuthenticationSecret(credential.password.withUnsafeBytes { Array($0) })
+            ))
+        }
+    }
+
+    public func removeAll() {
+        lock.withLock {
+            records.forEach { $0.password.clear() }
+            records.removeAll(keepingCapacity: false)
+        }
+    }
+}
+
 public struct SecureTerminalAuthenticationPrompt {
     public init() {}
 
@@ -227,7 +292,7 @@ public enum AuthenticationError: Error, Equatable, CustomStringConvertible {
     case originChanged
     case formChanged
     case accountNotFound
-    case privateContextCredentialUnavailable
+    case credentialAliasExists
     case vaultUnavailable
     case vaultLocked
     case userPresenceUnavailable
@@ -243,7 +308,7 @@ public enum AuthenticationError: Error, Equatable, CustomStringConvertible {
         case .originChanged: return "AUTH_ORIGIN_CHANGED"
         case .formChanged: return "AUTH_FORM_CHANGED"
         case .accountNotFound: return "AUTH_ACCOUNT_NOT_FOUND"
-        case .privateContextCredentialUnavailable: return "PRIVATE_CREDENTIAL_UNAVAILABLE"
+        case .credentialAliasExists: return "CREDENTIAL_ALIAS_EXISTS"
         case .vaultUnavailable: return "VAULT_UNAVAILABLE"
         case .vaultLocked: return "VAULT_LOCKED"
         case .userPresenceUnavailable: return "USER_PRESENCE_UNAVAILABLE"
@@ -261,8 +326,7 @@ public enum AuthenticationError: Error, Equatable, CustomStringConvertible {
         case .originChanged: return "The top-level authentication origin changed. Inspect the page again."
         case .formChanged: return "The authentication form changed. Inspect the page again."
         case .accountNotFound: return "No saved account matches that alias for this origin."
-        case .privateContextCredentialUnavailable:
-            return "Normal-profile credentials are unavailable in an isolated session."
+        case .credentialAliasExists: return "That credential alias already exists for this origin."
         case .vaultUnavailable: return "An approved operating-system credential vault is unavailable."
         case .vaultLocked: return "The operating-system credential vault is locked."
         case .userPresenceUnavailable:

apps/headless/Sources/HeadlessProtocol/Capabilities.swift

@@ -78,6 +78,7 @@ public struct BrowserEngineCapabilities: Sendable {
                     "storage": .string("engine-native-ephemeral-context"),
                     "sharedAcrossSessions": .bool(false),
                     "normalVaultAvailable": .bool(false),
+                    "ephemeralCredentials": .bool(true),
                     "destroyedOnClose": .bool(true),
                 ]),
                 "authentication": .object([
@@ -88,6 +89,7 @@ public struct BrowserEngineCapabilities: Sendable {
                     "savedCredentialUse": .bool(engine == .webkit),
                     "userPresencePerSavedUse": .bool(engine == .webkit),
                     "automaticActionReplay": .bool(false),
+                    "interactiveLogin": .bool(true),
                 ]),
             ]),
         ])
@@ -221,6 +223,7 @@ public let capabilitiesDocument: JSONValue = {
             "silentUse": .bool(false),
             "agentReceivesPasswords": .bool(false),
             "privateContextAccess": .bool(false),
+            "privateEphemeralCredentials": .bool(true),
         ]),
         "security": .object([
             "tcpListener": .bool(false),

apps/headless/Sources/HeadlessProtocol/HostCore.swift

@@ -145,6 +145,7 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
     private var trace: [String: [JSONValue]] = ["default": []]
     private var activeFlows: [String: [RecordedFlowStep]] = [:]
     private var recordings: [String: BrowserRecording] = [:]
+    private var privateAuthenticationBrokers: [String: EphemeralAuthenticationBroker]
     private var stopping = false
     private let traceStartedAt = ProcessInfo.processInfo.systemUptime
 
@@ -161,6 +162,8 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
         self.authenticationBroker = authenticationBroker
         self.authenticationChallenges = authenticationChallenges
         self.sessions = ["default": defaultSession]
+        self.privateAuthenticationBrokers = defaultSession.hostIsolated
+            ? ["default": EphemeralAuthenticationBroker()] : [:]
         self.shutdownHandler = shutdownHandler
     }
 
@@ -179,6 +182,7 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
                 trace.removeValue(forKey: name)
                 activeFlows.removeValue(forKey: name)
                 if let recording = recordings.removeValue(forKey: name) { stopped.append(recording) }
+                privateAuthenticationBrokers.removeValue(forKey: name)?.removeAll()
                 authenticationChallenges.invalidate(session: name)
             }
             return stopped
@@ -198,6 +202,8 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
             sessions.removeAll()
             trace.removeAll()
             activeFlows.removeAll()
+            privateAuthenticationBrokers.values.forEach { $0.removeAll() }
+            privateAuthenticationBrokers.removeAll()
             authenticationChallenges.removeAll()
             return (activeRecordings, openSessions)
         }
@@ -311,6 +317,8 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
             sessions.removeAll()
             trace.removeAll()
             activeFlows.removeAll()
+            privateAuthenticationBrokers.values.forEach { $0.removeAll() }
+            privateAuthenticationBrokers.removeAll()
             authenticationChallenges.removeAll()
             return (activeRecordings, openSessions)
         }
@@ -379,6 +387,9 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
             if sessions[name] != nil { return "SESSION_EXISTS" }
             sessions[name] = created
             trace[name] = []
+            if created.hostIsolated {
+                privateAuthenticationBrokers[name] = EphemeralAuthenticationBroker()
+            }
             return nil
         }
         if let rejection {
@@ -403,6 +414,7 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
             let recording = recordings.removeValue(forKey: name)
             trace.removeValue(forKey: name)
             activeFlows.removeValue(forKey: name)
+            privateAuthenticationBrokers.removeValue(forKey: name)?.removeAll()
             authenticationChallenges.invalidate(session: name)
             return (session, recording)
         }
@@ -554,30 +566,27 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
         let aliases: [AuthenticationAlias]
         let vaultAvailable: Bool
         let vaultStatus: String
-        if session.hostIsolated {
+        let broker = broker(for: sessionName, session: session)
+        do {
+            aliases = try broker.aliases(for: credentialOrigin)
+            vaultAvailable = true
+            vaultStatus = session.hostIsolated ? "private-ephemeral" : "available"
+        } catch let error as AuthenticationError {
             aliases = []
             vaultAvailable = false
-            vaultStatus = AuthenticationError.privateContextCredentialUnavailable.code
-        } else {
-            do {
-                aliases = try authenticationBroker.aliases(for: credentialOrigin)
-                vaultAvailable = true
-                vaultStatus = "available"
-            } catch let error as AuthenticationError {
-                aliases = []
-                vaultAvailable = false
-                vaultStatus = error.code
-            } catch {
-                aliases = []
-                vaultAvailable = false
-                vaultStatus = "VAULT_OPERATION_FAILED"
-            }
+            vaultStatus = error.code
+        } catch {
+            aliases = []
+            vaultAvailable = false
+            vaultStatus = "VAULT_OPERATION_FAILED"
         }
         let credentialUseAvailable: Bool
         let suggestion: String
         if session.hostIsolated {
-            credentialUseAvailable = false
-            suggestion = "Log in interactively without the normal credential vault; private credential enrollment is not available yet."
+            credentialUseAvailable = true
+            suggestion = aliases.isEmpty
+                ? "Run `headless auth login --interactive --session \(sessionName)` to enroll an ephemeral account."
+                : "Choose a private account alias or log in interactively."
         } else {
             #if os(macOS)
             credentialUseAvailable = true
@@ -593,7 +602,7 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
             "detection": .string("confirmed"),
             "accounts": .array(aliases.map(\.publicValue)),
             "expiresInSeconds": .number(AuthenticationChallengeStore.lifetime),
-            "userPresenceRequired": .bool(true),
+            "userPresenceRequired": .bool(!session.hostIsolated),
             "credentialUseAvailable": .bool(credentialUseAvailable),
             "vaultAvailable": .bool(vaultAvailable),
             "vaultStatus": .string(vaultStatus),
@@ -640,7 +649,9 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
             if interactive {
                 credential = try session.hostPromptCredential(origin: credentialOrigin)
             } else if let alias {
-                credential = try authenticationBroker.credential(for: credentialOrigin, alias: alias)
+                credential = try broker(for: sessionName, session: session).credential(
+                    for: credentialOrigin, alias: alias
+                )
             } else {
                 throw AuthenticationError.accountNotFound
             }
@@ -708,13 +719,25 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
            let saveAlias = try session.hostPromptCredentialSave(
                origin: credentialOrigin, account: saveCandidate.account
            ) {
-            try authenticationBroker.store(saveCandidate, for: credentialOrigin, alias: saveAlias)
+            try broker(for: sessionName, session: session).store(
+                saveCandidate, for: credentialOrigin, alias: saveAlias
+            )
             response["account"] = .string(saveAlias.rawValue)
             response["saved"] = .bool(true)
         }
         return .object(response)
     }
 
+    private func broker(
+        for sessionName: String, session: Engine.Session
+    ) -> any AuthenticationBroker {
+        if session.hostIsolated {
+            return withState({ privateAuthenticationBrokers[sessionName] })
+                ?? UnavailableAuthenticationBroker()
+        }
+        return authenticationBroker
+    }
+
     private func captureInfo(_ session: Engine.Session, name: String) throws -> JSONValue {
         let base = try session.hostCaptureInfo()
         guard case .object(var object) = base else { return base }