Authentication Flow

Relevant source files

The following files were used as context for generating this wiki page:

• src/web/store/session/user-store.ts
• src/web/store/session/login-flows.ts
• src/web/routes/inventory/login-flows.ts
• dashboard/views/users/index.ts
• README_EN.md

Authentication in freebuff-proxy consists of two distinct layers: control plane authentication for local users/admins and upstream credential acquisition for Freebuff accounts. The system manages local user identities via a JSON-backed store and coordinates Freebuff logins through a structured "callback" flow that polls the upstream provider for authorization status.

Local users interact with the web console using standard username/password credentials, while downstream agents use API keys formatted as sk-fb- strings to access OpenAI-compatible endpoints.

Local User Authentication

The UserStore class manages local identities, storing data in data/users.json. It handles password hashing using scrypt, API key generation, and role-based access control (RBAC) with admin and user roles.

Authentication Methods

1. Console Login: Users provide a username and password. The system verifies the passwordHash using a unique salt for each user.
2. API Key: Downstream agents include an Authorization: Bearer sk-fb-... header. The proxy validates this against the apiKey field in the user record.

Sources: src/web/store/session/user-store.ts:16-30, README_EN.md:124-135

The diagram shows the branching logic between web console logins and API-based authorization.

Data Model: UserRecord

Field	Type	Description
username	string	Unique identifier (2-64 characters).
salt	string	16-byte hex string for password hashing.
passwordHash	string	Result of scrypt(password, salt).
role	'admin'	'user'
apiKey	string	Prefixed with sk-fb- for agent access.
createdAt	string	ISO timestamp of user creation.

Sources: src/web/store/session/user-store.ts:16-25, src/web/store/session/user-store.ts:153-176

Upstream Freebuff Login Flow

Freebuff account authentication follows a specialized CLI-style flow. The proxy initiates a login request to the upstream provider, which returns a URL for the administrator to open in their local browser.

The Polling Mechanism

1. Initiation: The admin triggers a flow via POST /api/accounts/login.
2. Redirection: The proxy retrieves a loginUrl and fingerprintId from Freebuff.
3. Browser Action: The admin opens the URL and completes the sign-in on the official Freebuff site.
4. Verification: The LoginFlowManager polls the upstream loginStatus endpoint every 4 seconds.
5. Completion: Once the admin authorizes the login in their browser, the upstream returns an authToken. The proxy saves this to a local JSON file named after the account email.

Sources: src/web/store/session/login-flows.ts:25-34, src/web/store/session/login-flows.ts:70-85, src/web/routes/inventory/login-flows.ts:55-66

This sequence illustrates the asynchronous polling flow required to link an external Freebuff account to the proxy.

API Endpoints for Login Management

Endpoint	Method	Role	Purpose
/api/accounts/login	POST	Admin	Starts a new upstream login flow.
/api/accounts/login	GET	Admin	Lists all active and past login flows.
/api/accounts/login/:id	GET	Admin	Checks status (pending, done, expired) of a specific flow.
/api/accounts/login/:id/cancel	POST	Admin	Aborts a pending login flow.

Sources: src/web/routes/inventory/login-flows.ts:68-106

Security and Persistence

The proxy prioritizes data durability and security through restricted file permissions and atomic write operations.

• Atomic Saves: Data is written to a .tmp file before being renamed to the final destination (e.g., users.json), preventing corruption during crashes.
• File Permissions: The system attempts to set file modes to 0o600 (read/write by owner only) for sensitive files.
• Administrative Bootstrap: If no admin user exists, the system generates a default admin account. This is controlled by the ADMIN_PASSWORD environment variable or a random string printed in logs during the first start.
• Credential Masking: The web console masks API keys (e.g., sk-fb-xxxx...xxxx) to prevent accidental exposure during management.

Sources: src/web/store/session/user-store.ts:117-133, src/web/store/session/user-store.ts:219-250, dashboard/views/users/index.ts:333-337, README_EN.md:52-57

Conclusion

The authentication system effectively bridges local management with upstream account integration. By separating local UserRecords from external Freebuff authTokens, the proxy provides a secure, multi-user environment that scales across multiple Freebuff accounts while maintaining a standard OpenAI-compatible interface for downstream tools.