feat(core): register device metadata

[halvaradop]

Description

This pull request adds automatic device metadata collection and registration for the Stateful session strategy.

During authentication flows such as credential sign-in, OAuth/OIDC sign-in, and sign-up, the library now captures device information from the incoming request and stores it in the Device table. This information can be used to identify trusted devices, audit authentication activity, manage active sessions, and support future security features.

The device metadata is inferred primarily from the request headers, which are normalized and mapped into a consistent structure before being persisted.

Captured Metadata

The following information is collected when available:

• Platform
• Browser
• User agent
• Device fingerprint
• Client IP address
• Additional device metadata inferred from request headers

Request Headers

The following headers are used to infer device metadata:

Note: Header values are normalized and mapped into a consistent format to provide more accurate and predictable device information.

• user-agent
• sec-ch-ua-platform
• sec-ch-ua-mobile
• x-forwarded-for
• cf-connecting-ip
• x-real-ip
• x-client-ip
• ip

@coderabbitai ignore

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
auth	Skipped		Jul 31, 2026 12:18am

[coderabbitai]

📝 Walkthrough

Walkthrough

Session creation now receives requests, derives device metadata and fingerprints, creates device-linked stateful sessions, and updates OAuth cookie handling. Authentication tests and OAuth integration tests verify the new device associations and session cookie flow.

Changes

Stateful session and device integration

Layer / File(s)	Summary
Request-aware contracts and callers packages/core/src/@types/*, packages/core/src/api/*, packages/core/src/session/stateless.ts	Session creation accepts the originating request, and device creation inputs omit generated identifiers and timestamps.
Device metadata and session association packages/core/src/shared/utils.ts, packages/core/src/session/stateful.ts	Request headers and user-agent data produce device metadata and fingerprints; stateful sessions now reference created devices.
OAuth callback session handling packages/core/src/session/stateful.ts	OAuth callbacks synchronize profile data, persist refresh-token expiry, create device-linked sessions, and set the generated token hash in the session cookie.
Authentication and OAuth validation packages/core/test/**, packages/elysia/test/stateful/index.test.ts	Tests mock device creation, expect device-linked sessions, and validate authenticated session retrieval from the OAuth callback cookie.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Request
  participant OAuthCallback
  participant createDevice
  participant DevicesAdapter
  participant StatefulSessionStorage
  participant SessionCookie
  Request->>OAuthCallback: OAuth callback request
  OAuthCallback->>createDevice: Extract request device data
  createDevice->>DevicesAdapter: Create device record
  OAuthCallback->>StatefulSessionStorage: Create device-linked session
  OAuthCallback->>SessionCookie: Set session token hash and CSRF cookie

Loading

Possibly related PRs

• aura-stack-ts/auth#227: Introduces the device adapter contract extended by this change.
• aura-stack-ts/auth#228: Adds the stateful session strategy extended with request-aware creation.
• aura-stack-ts/auth#239: Adds the persistence support used for device-linked sessions.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: registering device metadata during session creation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/register-device-info

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/core/src/session/stateful.ts`:
- Around line 1346-1356: Update the OAuth session creation flow around
createHash and config.adapter.createSession to retain the raw session token
separately, store only its hash in tokenHash, and return/set the raw token as
the cookie value. Ensure getSessionByToken receives the unhashed token, matching
the credential flow behavior.
- Around line 45-62: Update createDevice to call
config.adapter.getDeviceByFingerprint after generating the fingerprint, scoped
to the user. If a device exists, update its lastSeenAt and lastIp and return it;
otherwise retain the existing creation flow with firstSeenAt initialized for the
new device.
- Around line 1319-1321: Update the createOAuthAccount branch to persist
refreshTokenExpiresAt using the same accessToken.refresh_token_expires_in
conversion as the existing-account update path, returning null when the provider
omits the expiry. Keep the existing-account behavior unchanged.

In `@packages/core/src/shared/utils.ts`:
- Around line 282-285: Reorder the user-agent checks in the device
classification logic so the TV pattern is evaluated before the generic mobile
pattern. Keep the existing tablet, mobile, and bot classifications unchanged
otherwise, ensuring Android TV user agents return "tv" instead of "mobile".

In `@packages/core/test/actions/callback/stateful.test.ts`:
- Line 336: Strengthen the new-user OAuth tests around the device creation
assertions near createDeviceMock and lines 419-435: use a user-specific fixture
or factory, assert createDevice received the expected userId and device fields,
and verify the persisted session is associated with that same user/device owner
instead of only checking invocation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 537c3056-b565-40c3-9f22-a715e862fdc1

📥 Commits

Reviewing files that changed from the base of the PR and between 1d80074 and 6e09b7f.

📒 Files selected for processing (14)

• packages/core/src/@types/adapter.ts
• packages/core/src/@types/session.ts
• packages/core/src/api/signInCredentials.ts
• packages/core/src/api/signUp.ts
• packages/core/src/session/stateful.ts
• packages/core/src/session/stateless.ts
• packages/core/src/shared/utils.ts
• packages/core/test/actions/callback/stateful.test.ts
• packages/core/test/actions/signIn/signInCredentials/stateful.test.ts
• packages/core/test/actions/signUp/stateful.test.ts
• packages/core/test/api/stateful/signInCredentials.test.ts
• packages/core/test/api/stateful/signUp.test.ts
• packages/core/test/presets.ts
• packages/elysia/test/stateful/index.test.ts