Login Audit

Login Audit

Login Audit records Capell user access history. It wraps Rappasoft's authentication log package with Capell settings, a Filament resource, a dashboard widget, user-resource bridge fields, and IP retention controls.

At A Glance

• Package: capell-app/login-audit
• Namespace: Capell\LoginAudit\
• Surfaces: Filament admin, database
• Service providers: packages/login-audit/src/Providers/AdminServiceProvider.php, packages/login-audit/src/Providers/LoginAuditServiceProvider.php
• Capell dependencies: capell-app/admin
• Third-party dependencies: rappasoft/laravel-authentication-log, tapp/filament-authentication-log

Why It Helps Your Capell Workflow

• Records login, failed login, logout, and throttled admin/user activity metadata so operators can investigate account activity from Capell.
• Helps owners spot authentication patterns without adding a bespoke security report to each project.
• Pairs with password policy and diagnostics to make account safety visible as an operational workflow.

Best Used With

• Password Policy
• Diagnostics
• Dashboard Reports

What It Adds

Login Audit records login, failed login, logout, and last-activity metadata for Capell users.

• Filament resource for authentication logs.
• Dashboard widget for recent access activity.
• Settings schema for retention, IP tracking, admin activity tracking, resource visibility, and user-resource bridge fields.
• Persistent admin middleware and frontend middleware alias for throttled activity tracking.
• User edit sidebar summary and relation manager when the bridge is enabled.

Why It Matters

For developers: The package keeps vendor logging in place but routes Capell-specific behaviour through Actions, settings, bridges, and resource configurators.

For teams: Operators can review access history, failed logins, IP addresses, user agents, and recent activity without opening database records.

Built With

This package makes its Composer dependencies visible because they are part of the value proposition, not just plumbing. When an upstream package has a public repository, its linked preview card points readers back to the maintainers so their work gets proper credit.

Capell packages used here

• Capell Admin

Open-source packages used here

• Laravel Authentication Log - authentication event storage for login, logout, IP, and user-agent history.
• Filament Authentication Log - the Filament UI layer for reviewing authentication activity inside the admin panel.

Linked package previews

Screens And Workflow

Screenshots are generated from docs/screenshots.json during package deployment.

• Authentication logs admin index.
• Authentication log table filters.
• Dashboard widget.
• Authentication log settings screen.
• User edit access summary.
• User authentication logs relation manager.

Technical Shape

• LoginAuditServiceProvider registers config, translations, migrations, settings, protected table metadata, the frontend.activity middleware alias, and the LoginAudit model override.
• AdminServiceProvider registers the admin bridge, Filament resource, dashboard widget, settings contributor, persistent admin middleware, and daily authentication-log:purge schedule.
• LoginAuditResource extends Tapp\FilamentAuthenticationLog\Resources\AuthenticationLogResource and replaces the table with LoginAuditsTable.
• AdminActivityMiddleware and UserActivityMiddleware update matching audit rows without changing unrelated vendor audit state.

Code Map

Admin Surface

• Resources: LoginAuditResource.
• Widgets: LoginAuditsWidget.
• Settings: LoginAuditSettingsSchema.
• User resource bridge: LoginAuditUserSchemaExtender adds access summary state and LoginAuditsRelationManager when the host user model supports authentication logs.

Session Boundary

Login Audit reports active sessions and device context from authentication-log rows. It does not terminate sessions directly: logout-other-devices and per-device revocation depend on the host app's session driver, guard setup, and remember-token policy. Pair this package with the host auth stack, Password Policy, Access Gate, or a session-management package when destructive session controls are required.

Data And Persistence

• login_audit stores authenticatable type/id, IP address, user agent, login time, and logout time.

• Records belong polymorphically to authenticatable users.

• Config purge value defaults to 365 days and is overridden by the Login Audit retention setting before the daily purge runs.

• ApplyLoginAuditSettingsAction applies retention and IP tracking settings before the scheduled purge runs.

• last_purged_at records the last successful scheduled purge callback for operator visibility.

• ResolveLoginAuditIpAddressAction reads the configured CDN header when login-audit.behind_cdn is enabled; otherwise it uses the request IP.

• enable_geo_location controls the vendor geo lookup for new-device and failed-login events. Keep it disabled unless the host app has a configured geo provider and a lawful basis for storing location data.

• Models: LoginAudit.

• Migrations: 2026_05_10_190857_01_create_login_audit_table.php.

• Config: packages/login-audit/config/login-audit.php.

Extension Points

• Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

Install Impact

• Adds login_audit table.
• Adds settings migration.
• Adds authentication log admin resource and widget.
• Listens to Laravel auth events configured in login-audit.php.
• May send new-device or failed-login notifications depending on config.

Install And Setup

• Install with composer require capell-app/login-audit in the host Capell application.
• Run migrations through the host application package install flow.
• In this repository, verify package changes with vendor/bin/pest; do not use php artisan.

Laravel 13 dependency note

Until rappasoft/laravel-authentication-log merges Laravel 13 support from PR #140, host Laravel 13 apps need the PR fork as a root Composer repository and alias:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/fdemb/laravel-authentication-log"
        }
    ],
    "require": {
        "rappasoft/laravel-authentication-log": "dev-main as 6.0.1"
    }
}

The package itself keeps the normal ^6.0|^5.0 dependency so it can move back to upstream tags when Laravel 13 support is released.

Admin And Access

• LoginAuditResource (packages/login-audit/src/Filament/Resources/LoginAudits/LoginAuditResource.php)

• LoginAuditsWidget (packages/login-audit/src/Filament/Widgets/LoginAuditsWidget.php)

• LoginAuditSettingsSchema (packages/login-audit/src/Filament/Settings/LoginAuditSettingsSchema.php)

• LoginAuditsRelationManager (packages/login-audit/src/Filament/Resources/Users/RelationManagers/LoginAuditsRelationManager.php)

• LoginAuditsWidget is gated by admin and super_admin roles and the login_audits dashboard setting.

• The user-resource bridge is controlled by the package settings and the host admin bridge support.

Screenshot Coverage

The Laravel 13 demo harness has screenshots for the Login Audit resource, table filters, settings schema, dashboard/widget configuration, user edit access summary, and user relation use case. The relation use case requires the host user model to expose Rappasoft's authentications() relationship, normally by using AuthenticationLoggable.

Common Pitfalls

• Set CDN IP header config before trusting IP addresses behind a proxy.
• Confirm notification settings before production rollout.
• Run migrations before loading the resource.
• In Laravel 13 apps, install the Rappasoft PR fork at the root app level until upstream ships a compatible tag.

Docs

• docs index
• credits-and-acknowledgements.md
• overview.md
• settings-and-ip-resolution.md

Testing

Run package tests from the repository root:

vendor/bin/pest packages/login-audit/tests --configuration=phpunit.xml

Maintenance Notes

• Put behaviour changes in src/Actions/; UI classes, commands, and controllers should call actions instead of owning domain logic.

Login Audit

Status: Available, schema-owning · Kind: package · Tier: premium · Bundle: operations · Contexts: admin · Product group: Capell Operations

This page is the implementation overview for the Login Audit package. It is based on the package README, providers, migrations, config, Filament resources, Actions, middleware, and tests.

What This Package Adds

Login Audit records login, failed login, logout, and last-activity metadata for Capell users.

• Filament resource for authentication logs.
• Dashboard widget for recent authentication activity.
• Settings schema for authentication log behaviour.
• Middleware for admin and user activity tracking.
• User edit sidebar summary and authentication logs relation manager when the bridge is enabled.
• CSV exports from the global authentication log and per-user authentication history.
• Suspicious-login detection for repeated failures, failed-device success, rapid country changes, and optional unusual login hours.
• Capell admin alerts for new-device, failed-login, and suspicious-login audit events.

Developer Notes

The package uses rappasoft/laravel-authentication-log for event capture and storage, then layers Capell-specific settings, Actions, resources, widgets, bridge fields, and IP retention policy on top.

• LoginAuditServiceProvider registers config, translations, migrations, settings, protected table metadata, the frontend.activity middleware alias, and the LoginAudit model override.
• AdminServiceProvider registers the admin bridge, Filament resource, dashboard widget, settings contributor, persistent admin middleware, and daily authentication-log:purge schedule.
• LoginAuditResource extends Tapp\FilamentAuthenticationLog\Resources\AuthenticationLogResource and replaces the table with LoginAuditsTable.
• AdminActivityMiddleware and UserActivityMiddleware update matching audit rows without changing unrelated vendor audit state.

Operational Notes

Helps site operators review access activity and spot account behaviour that needs follow-up.

• Adds login_audit table.
• Adds settings migration.
• Adds authentication log admin resource and widget.
• Exports access logs as CSV for incident review and compliance handoff.
• Marks suspicious audit rows using configurable failed-attempt and unusual-login heuristics.
• Sends persistent Filament/database alerts to the Login Audit security alert notification group.
• Listens to Laravel auth events configured in login-audit.php.
• May send new-device or failed-login notifications depending on config.

Data And Retention

• login_audit stores authenticatable type/id, IP address, user agent, login time, and logout time.
• Records belong polymorphically to authenticatable users.
• Config purge value defaults to 365 days and is synced from the Login Audit retention setting before the daily purge runs.

Screenshot Plan

• Authentication logs admin index.
• Authentication log table filters.
• Dashboard widget.
• Authentication log settings screen.

Screenshots

User access summary screenshot target: packages/login-audit/docs/screenshots/user-edit-access-summary.png. Keep this as text until the screenshot file is committed.

User authentication logs relation manager screenshot target: packages/login-audit/docs/screenshots/user-login-audits-relation-manager.png. Keep this as text until the screenshot file is committed.

Pitfalls

• Set CDN IP header config before trusting IP addresses behind a proxy.
• Confirm notification settings before production rollout.
• Run migrations before loading the resource.
• In Laravel 13 apps, use the fdemb/laravel-authentication-log PR fork at the root app level until upstream ships Laravel 13 support.

Verification

• Run vendor/bin/pest packages/login-audit/tests --configuration=phpunit.xml.
• Run the relevant host-app migration or package install flow in a disposable database.
• Open the listed admin or frontend surface and compare it with the screenshot plan.

Package Manifest

• Composer name: capell-app/login-audit
• Product group: Capell Operations
• Kind: package
• Tier: premium
• Bundle: operations
• Contexts: admin
• Requires: capell-app/admin
• Optional dependencies: None listed.

Laravel 13 Dependency Note

rappasoft/laravel-authentication-log PR #140 adds Laravel 13 support. Until that PR is released upstream, Laravel 13 host apps need the fork as a root Composer repository and alias:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/fdemb/laravel-authentication-log"
        }
    ],
    "require": {
        "rappasoft/laravel-authentication-log": "dev-main as 6.0.1"
    }
}

Keep packages/login-audit/composer.json on the normal ^6.0|^5.0 constraint. Composer inline aliases are root-only, so the fork alias belongs in the consuming Laravel app, not inside the package dependency list.

Admin Surfaces

• LoginAuditResource (packages/login-audit/src/Filament/Resources/LoginAudits/LoginAuditResource.php)
• LoginAuditsWidget (packages/login-audit/src/Filament/Widgets/LoginAuditsWidget.php)
• LoginAuditSettingsSchema (packages/login-audit/src/Filament/Settings/LoginAuditSettingsSchema.php)
• LoginAuditsRelationManager (packages/login-audit/src/Filament/Resources/Users/RelationManagers/LoginAuditsRelationManager.php)

Commands

• None proven in this package directory.

Routes And Config

• Config: packages/login-audit/config/login-audit.php

Permissions And Gates

• Gate: LoginAuditsWidget: admin, super_admin

Migrations

• Migration: create_login_audit_table.php
• Settings migration: add_login_audit_settings.php

ERD Excerpt

erDiagram
    USERS ||--o{ AUTHENTICATION_LOG : records

    AUTHENTICATION_LOG {
        bigint id PK
        string authenticatable_type
        bigint authenticatable_id
        string ip_address
        text user_agent
        timestamp login_at
        timestamp logout_at
    }

Screenshot Automation

Deployment should read screenshots.json, install the package with demo data, resolve each admin surface or frontend URL, and write images to packages/login-audit/docs/screenshots.

• Authentication logs admin index: seeded audit records for the demo admin user.
• Authentication log table filters: filter drawer and date/success controls.
• Dashboard/widget configuration: Access Logs contribution available in dashboard settings.
• Authentication log settings screen: retention, IP tracking, visibility, and user bridge settings.
• User edit access summary: recent login, failed attempt, device, and active-session counts.
• User authentication logs relation use case: requires the host user model to expose authentications(), normally through Rappasoft's AuthenticationLoggable trait.