Session tokens

Passwork uses a token-based authentication model with Access Token / Refresh Token pair.

Token system overview

Token	Purpose	Lifetime
Access Token	API request authentication	~2.8 hours
Refresh Token	Access Token renewal	36 hours

Why not JWT?

Passwork tokens are random strings, not JWT. For a password manager, this approach provides higher security:

Characteristic	Passwork tokens	JWT
Format	Random Base64 string	JSON with signature
Information in token	None	Payload with data
Validation	Database lookup	Signature verification
Token revocation	Instant (DB deletion)	Requires blacklist

Security advantages:

• Instant session revocation. If compromise is suspected, administrator or user can immediately terminate any session — token is deleted from database and immediately becomes invalid. JWT continues working until expiration.

• Full session control. All active sessions are stored on server, allowing tracking devices, IP addresses, and last activity time. Administrator sees complete picture and can manage access.

• No sensitive data in token. JWT contains payload with user information that can be read (Base64 is not encryption). Passwork tokens are simply random identifiers without any information.

• Key compromise resistance. If JWT secret key leaks, attacker can create valid tokens for any user. With session tokens, this attack vector doesn't exist.

• No signing secret key. JWT requires storing private key on server for token signing — another secret to protect, rotate, and control. Passwork session tokens are just random strings, no secret keys needed for generation.

---

Access Token

Characteristics

Parameter	Value
Length	256 bits
Format	Base64
String length	~44 characters
Entropy	256 bits
Default lifetime	10,000 seconds (~2.8 hours)

Generation

Access Token is generated with cryptographically secure random number generator:

token = base64(random_bytes(32))

Validation

On each request, server:

1. Extracts token (from cookie or header, depending on mode)
2. Looks up token in database
3. Checks lifetime
4. Links request to user

---

Token transmission modes

Passwork uses two Access Token transmission modes depending on client type:

Browser Mode (web application)

For web application, Access Token is transmitted via HttpOnly Cookie:

Parameter	Value
HttpOnly	Yes — inaccessible to JavaScript (XSS protection)
Secure	Yes — HTTPS only
SameSite	Strict — CSRF protection

In this mode, browser automatically attaches cookie to each request. Access Token is not returned in response body during authentication — only in Set-Cookie header.

API Mode (desktop, extension, mobile)

For API clients, Access Token is transmitted in Authorization header:

Authorization: Bearer {access_token}

In this mode, Access Token is returned in response body during authentication, and client manages storage independently.

Mode comparison

Parameter	Browser Mode	API Mode
Clients	Web application	Desktop, Extension, Mobile
Token transmission	HttpOnly Cookie	Authorization header
XSS protection	✓ (HttpOnly)	Depends on client
Token management	Browser (automatic)	Client (manual)

---

Refresh Token

Characteristics

Parameter	Value
Length	256 bits
Format	Base64
String length	~44 characters
Entropy	256 bits
Default lifetime	129,600 seconds (36 hours)

Purpose

Refresh Token is used to obtain new Access Token without re-authentication. More on renewal process in Token rotation section.

---

Lifetime configuration

By user roles

Token lifetime is configured at user role level:

Setting	Default value
Access Token lifetime	10,000 sec (~2.8 hours)
Refresh Token lifetime	129,600 sec (36 hours)

Configuration examples

Scenario	Access TTL	Refresh TTL
Standard user	10,000 sec	129,600 sec
High security	1,800 sec (30 min)	14,400 sec (4 hours)
Convenience	28,800 sec (8 hours)	604,800 sec (7 days)

---

Session lifecycle

Complete lifecycle

T=0: Authentication. User enters credentials. Server creates Access Token (TTL: 2.8 hours) and Refresh Token (TTL: 36 hours).

T=2.8h: Access Token expired. Client sends Refresh Token. Server issues new tokens. Old Refresh Token is invalidated.

T=36h: Refresh Token expired. Re-authentication required. User enters credentials again.

Alternative scenario — Logout. User clicks "Logout". Both tokens are invalidated. Session terminated.

Token invalidation

All session tokens are invalidated on:

• User logout
• Master password change
• Administrator master password reset

---

Token rotation

Standard mode (applications)

For web application, browser extension, mobile and desktop apps, strict token rotation policy applies.

When refreshing session, client sends Access Token and Refresh Token simultaneously, and receives new token pair in response. This provides continuous rotation of both tokens, preventing reuse of stolen tokens.

Automation mode (API)

For DevOps tasks and automation, strict rotation is often inconvenient. Therefore, for sessions created via API token generation, alternative mode is available:

• Access Token only refresh without Refresh Token change
• Separate Refresh Token renewal when needed

This allows using long-lived Refresh Tokens in scripts and CI/CD pipelines.

---

Token security

Interception protection

Threat	Protection
Network interception	HTTPS/TLS required
XSS attack	HttpOnly cookies (Browser Mode)
CSRF	CSRF Token + SameSite cookies

---

CSRF Token

Purpose

CSRF Token protects against cross-site request forgery attacks. Required for all modifying operations.

Characteristics

Parameter	Value
Size	256 bits
Format	Hexadecimal (64 characters)
Entropy	256 bits
Generator	Cryptographically secure

Usage

CSRF Token is transmitted in header of each request:

X-CSRF-Token: {csrf_token}

Requirements by client type

Client type	CSRF Token
Web application (Browser Mode)	✓ Required (generated and validated automatically)
Browser extension	Optional (on client request)
Mobile application	Optional (on client request)
API	— (not used)

---

Cookie Sign

Purpose

Optional additional protection feature for Browser Mode. Binds session to client context, protecting against cookie theft and session hijacking.

How it works

When enabled, server computes signature based on:

• Client IP address
• Browser User-Agent
• Session identifier
• Secret key (60 characters, ~357 bits entropy)

Signature is computed by formula:

cookieSign = HMAC-SHA512(IP + UserAgent + SessionID, secret)

Signature is saved in separate HttpOnly cookie and verified on each request.

Attack protection

Attack	Protection
Session Hijacking	Stolen cookie doesn't work from different IP
Cookie Theft	Cookie useless without matching IP + User-Agent

Limitations

• IP change (VPN, mobile network) requires re-authentication
• Browser update may change User-Agent

Enabling

Feature is enabled by administrator in system settings. Disabled by default for compatibility with users with dynamic IP.

---

Client types

Passwork distinguishes four client types with different security mechanisms:

Feature	Web	Browser Extension	Mobile	API
Token transmission mode	Browser Mode	API Mode	API Mode	API Mode
Access Token	Cookie	Header	Header	Header
CSRF Token	✓ Required	Optional	Optional	—
Cookie Sign	Optional	—	—	—
PIN code	—	✓ Supported	—	—

Browser Extension — only client type supporting server-side PIN code. PIN is verified on server, which opens temporary window for API use. After timeout, session is locked until PIN re-entry. On multiple incorrect attempts, server immediately terminates session. This protects against token theft — even with token compromise, attacker cannot use API without knowing PIN.

---

HTTP headers

Authentication headers

Header	Description	Mode
Authorization	Access Token (Bearer {token})	API Mode
Cookie	Access Token (automatic)	Browser Mode
X-CSRF-Token	CSRF protection	All modes
X-Master-Key-Hash	Master key hash	When needed

---

Client-side token storage

Each client type implements secure token storage according to platform capabilities:

• Web application — Access Token stored in HttpOnly Cookie, inaccessible to JavaScript (XSS protection)
• Desktop and Mobile apps — tokens stored in OS secure storage with restricted access
• Browser extension — isolated browser storage used, inaccessible from web pages

---

Multiple sessions

Parallel sessions

Passwork supports multiple simultaneous sessions:

• User can be authenticated on multiple devices
• Each device has its own token pair
• Logout on one device doesn't affect others

Session management

User can:

• View list of active sessions
• Terminate specific session
• Terminate all sessions (except current)

Administrator can:

• Force terminate all user sessions

---

Configuration recommendations

High security

Parameter	Value
Access Token	30 minutes
Refresh Token	4 hours

• Frequent re-authentication
• Short attack window
• Suitable for critical systems

Security and convenience balance (default)

Parameter	Value
Access Token	~2.8 hours
Refresh Token	36 hours

• Workday without re-authentication
• Refresh Token for ~1.5 workdays
• Suitable for most organizations

Maximum convenience

Parameter	Value
Access Token	8 hours
Refresh Token	7 days

• Authentication once a week
• Suitable for low-risk scenarios
• Not recommended for critical data

LLM version