update docs

Author: Abhishek5Sharma

CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **BREAKING: Magic-link authentication rebuilt as stateful, single-use tokens** — replaces the stateless signed-URL flow. Opaque, high-entropy tokens are stored **hashed** (SHA-256) in the new `magic_link_tokens` table; only the plain token ever leaves the app (in the emailed URL).
+  - **Single-use by deletion** — the token row is deleted on successful redemption, so a link can never be replayed. Generating a new link **invalidates the user's previous link** for that channel.
+  - **Config-driven, extensible channels** — new `magic_link.channels` config (`web`, `mobile`, and any host-defined channel such as `desktop`, added by config with no code change). A channel with a `scheme`/`universal_link` is built as a deep link; otherwise `base_url` + `path`. Send accepts a `channel` parameter.
+  - **Optional browser/device binding** (`magic_link.bind_to_browser`) and **confirmation-required flow** (`magic_link.require_confirmation`) to defeat email-scanner auto-consumption.
+  - **Single route for login + confirmation** — `GET|POST /neev/loginUsingLink` (API) and `GET|POST /login-link/verify` (Blade): GET opens the link (validate-only when confirmation is required), POST is the explicit confirm. New `GET|POST /neev/loginUsingLink/validate` checks a token without consuming it. Redemption routes are now rate-limited (`throttle:10,1`).
+  - **New `magic_link` config block** — single engine (no driver switch): `expires_in` (default 10 min), `bind_to_browser`, `require_confirmation`, `channels`. The legacy `url_expiry_time` no longer governs magic links (still used by password-reset / email-verification links).
+  - **API surface** — `MagicLinkManager` service (inject it; no facade). `forWeb()`/`forMobile()`/`generate()` return an array (`url`, `token`, `expires_in`, `channel`, `model`); `validate()`/`consume()` return a `MagicLinkResult` whose status is a string constant (`MagicLinkResult::VALID`, `EXPIRED`, `INVALID`, `BINDING_MISMATCH`, `PENDING_CONFIRMATION`, `INACTIVE_USER`). Token mechanics (`generateToken`/`hashToken`/`findByToken`) live on the `MagicLinkToken` model.
+  - **Removed the legacy web route** `GET /login/{id}` (`login.link`); the Blade flow now redeems at `GET|POST /login-link/verify` (`login.link.verify`).
+  - Note: a valid magic link still completes login **without** enforcing MFA (unchanged, by design).
+
+### Added
+- **Lifecycle events** — `MagicLinkGenerated`, `MagicLinkConsumed`, `MagicLinkRejected` for auditing, notifications, and abuse detection.
+- **`neev:clean-magic-links` command** — deletes expired magic-link tokens; schedule alongside `neev:clean-login-attempts`.
+
 ## [0.5.0] - 2026-07-02
 
 ### Added

README.md

@@ -176,12 +176,12 @@ curl -X POST https://yourapp.com/neev/login \
 ### Magic Link (Passwordless)
 
 ```bash
-# Send login link
+# Send login link (single-use token; optional channel, default "web")
 curl -X POST https://yourapp.com/neev/sendLoginLink \
-  -d '{"email": "john@example.com"}'
+  -d '{"email": "john@example.com", "channel": "web"}'
 
-# Login via link
-curl -X GET "https://yourapp.com/neev/loginUsingLink?id=1&signature=..."
+# Login via link (opaque token from the email URL)
+curl -X GET "https://yourapp.com/neev/loginUsingLink?token=THE_OPAQUE_TOKEN"
 ```
 
 ### Passkey / WebAuthn
@@ -227,7 +227,8 @@ All API routes are prefixed with `/neev` — the prefix is configurable via `rou
 | POST | `/neev/register` | Register new user | No |
 | POST | `/neev/login` | Login with credentials | No |
 | POST | `/neev/sendLoginLink` | Send magic link | No |
-| GET | `/neev/loginUsingLink` | Login via magic link | No |
+| GET / POST | `/neev/loginUsingLink` | Redeem magic link (GET opens, POST confirms) | No |
+| GET / POST | `/neev/loginUsingLink/validate` | Validate a magic-link token without using it | No |
 | POST | `/neev/logout` | Logout current session | Yes |
 | POST | `/neev/logoutAll` | Logout all other sessions | Yes |
 | POST | `/neev/forgotPassword` | Send password reset link | No |
@@ -346,7 +347,7 @@ The Blade page routes below (everything except the OAuth/SSO endpoints) register
 | PUT | `/login` | `login.password` | Show password form |
 | POST | `/login` | - | Process login |
 | POST | `/login/link` | `login.link.send` | Send magic link |
-| GET | `/login/{id}` | `login.link` | Login via magic link |
+| GET / POST | `/login-link/verify` | `login.link.verify` | Redeem magic link (GET opens, POST confirms) |
 | GET | `/forgot-password` | `password.request` | Forgot password form |
 | POST | `/forgot-password` | `password.email` | Send reset link |
 | GET | `/update-password/{id}/{hash}` | `reset.request` | Reset password form |
@@ -669,7 +670,8 @@ Email verification is enforced by applying the opt-in `neev:verified-email` midd
 ```php
 'login_token_expiry_minutes' => 1440,  // Login access tokens
 'mfa_jwt_expiry_minutes' => 30,        // Temporary MFA JWTs
-'url_expiry_time' => 60,               // Magic links, reset links
+'url_expiry_time' => 60,               // Password-reset & email-verification links
+'magic_link' => ['expires_in' => 10],  // Magic links (single-use, stateful)
 'otp_expiry_time' => 15,               // OTP codes
 ```
 

docs/api-reference.md

@@ -117,7 +117,9 @@ When `auth_state` is `mfa_required`, the token is a short-lived JWT (type `mfa`)
 
 ### Send Login Link
 
-Send a magic link to the user's email for passwordless login.
+Send a magic link to the user's email for passwordless login. Issues a
+single-use token (stored hashed) and invalidates the user's previous link for
+the channel.
 
 ```http
 POST /neev/sendLoginLink
@@ -127,10 +129,14 @@ POST /neev/sendLoginLink
 
 ```json
 {
-    "email": "john@example.com"
+    "email": "john@example.com",
+    "channel": "web"
 }
 ```
 
+`channel` is optional (default `web`); it must be a channel defined in
+`magic_link.channels`.
+
 **Response:**
 
 ```json
@@ -139,27 +145,64 @@ POST /neev/sendLoginLink
 }
 ```
 
+Returns `401` for an unknown email.
+
 ---
 
 ### Login Using Link
 
-Authenticate using a magic link.
+Redeem a magic link. Login and the optional confirmation step share this route:
+`GET` opens the link, `POST` is the explicit confirm. When
+`magic_link.require_confirmation` is on, a `GET` only validates and returns
+`{"auth_state": "confirmation_required"}` without logging in.
 
 ```http
-GET /neev/loginUsingLink?id={email_id}&signature={signature}&expires={timestamp}
+GET|POST /neev/loginUsingLink?token={token}
 ```
 
-**Response:**
+**Response (success):**
 
 ```json
 {
     "auth_state": "authenticated",
     "token": "1|abc123...",
     "expires_in": 1440,
+    "mfa_options": null,
     "email_verified": true
 }
 ```
 
+- `403 { "message": "Invalid or expired verification link." }` — invalid, expired, replayed, or binding-mismatch token.
+- `422` with an `email` validation error — the account is deactivated.
+
+The token is single-use: the row is deleted on success, so replays return `403`.
+
+---
+
+### Validate Login Link
+
+Check a magic-link token **without** consuming it (e.g. to render a
+confirmation screen). Never authenticates.
+
+```http
+GET|POST /neev/loginUsingLink/validate?token={token}
+```
+
+**Response:**
+
+```json
+{
+    "status": "pending_confirmation",
+    "valid": false,
+    "requires_confirmation": true,
+    "channel": "web",
+    "email_verified": true
+}
+```
+
+`status` is one of `valid`, `invalid`, `expired`, `binding_mismatch`,
+`pending_confirmation`, `inactive_user`.
+
 ---
 
 ### Logout

docs/authentication.md

@@ -165,13 +165,21 @@ Enforcement is opt-in: apply the `neev:password-not-expired` middleware alias (`
 
 Passwordless login via secure email links. Always available — no config toggle.
 
+Magic links are **stateful and single-use**: an opaque, high-entropy token is
+stored **hashed** in the `magic_link_tokens` table (only the plain token ever
+leaves the app, inside the emailed URL). On successful use the row is **deleted**,
+so a link can never be replayed, and issuing a new link **invalidates the user's
+previous link** for that channel.
+
+> A valid magic link completes login **without** enforcing MFA, even if the user
+> has MFA enabled (by design — same posture as OAuth login). See [security.md](./security.md).
+
 ### Flow
 
-1. User enters email on login page
-2. Clicks "Send Login Link"
-3. Receives email with secure link
-4. Clicks link to authenticate
-5. Automatically logged in
+1. User enters email and requests a link (`POST /neev/sendLoginLink`)
+2. Receives an email with a secure link containing an opaque `token`
+3. Opens the link → the token is validated and consumed
+4. Automatically logged in (web: session; API: a login token)
 
 ### API Example
 
@@ -180,23 +188,56 @@ Passwordless login via secure email links. Always available — no config toggle
 ```bash
 curl -X POST https://yourapp.com/neev/sendLoginLink \
   -H "Content-Type: application/json" \
-  -d '{"email": "john@example.com"}'
+  -d '{"email": "john@example.com", "channel": "web"}'
 ```
 
 **Use Link:**
 
 ```bash
-curl -X GET "https://yourapp.com/neev/loginUsingLink?id=1&signature=abc123&expires=1234567890"
+curl -X GET "https://yourapp.com/neev/loginUsingLink?token=THE_OPAQUE_TOKEN"
 ```
 
-### Link Expiry
+Login and the (optional) confirmation step share one route: `GET` opens the link,
+`POST` is the explicit confirm. `GET|POST /neev/loginUsingLink/validate` checks a
+token without consuming it. Redemption is rate-limited (`throttle:10,1`).
+
+### Channels
 
-Configure in `config/neev.php`:
+`sendLoginLink` accepts a `channel` (default `web`). Channels are config-driven —
+add your own (e.g. `desktop`) under `magic_link.channels` with no code change. A
+channel with a `scheme`/`universal_link` builds a deep link; otherwise a web URL.
+
+### Configuration & options
+
+Configured under `magic_link` in `config/neev.php`:
 
 ```php
-'url_expiry_time' => 60,  // Minutes
+'magic_link' => [
+    'expires_in' => 10,              // minutes a link stays valid
+    'bind_to_browser' => false,      // restrict redemption to the originating browser/device
+    'require_confirmation' => false, // require an explicit confirm step (defeats email scanners)
+    'channels' => [ /* web, mobile, ... */ ],
+],
 ```
 
+See [configuration.md](./configuration.md#magic-link) for the full block.
+
+### Calling it in code
+
+Inject the `MagicLinkManager` service (there is no facade):
+
+```php
+use Ssntpl\Neev\Services\MagicLink\MagicLinkManager;
+
+$link = $magicLink->forWeb($user);   // ['url', 'token', 'expires_in', 'channel', 'model']
+$result = $magicLink->consume($request);
+if ($result->isValid()) { /* $result->user is authenticated */ }
+```
+
+Lifecycle events `MagicLinkGenerated`, `MagicLinkConsumed`, and `MagicLinkRejected`
+are fired for auditing/notifications. Prune expired tokens with
+`php artisan neev:clean-magic-links`.
+
 ---
 
 ## Passkey / WebAuthn Authentication

docs/cli-commands.md

@@ -78,6 +78,21 @@ Retention is controlled by `config('neev.mfa_pending_setup_retention_days')` (de
 $schedule->command('neev:clean-pending-mfa-setups')->daily();
 ```
 
+### `neev:clean-magic-links`
+
+Delete expired magic-link tokens. (Consumed and superseded tokens are already
+deleted on use, so only expired rows can linger.)
+
+```bash
+php artisan neev:clean-magic-links
+```
+
+Schedule it alongside the other maintenance commands:
+
+```php
+$schedule->command('neev:clean-magic-links')->daily();
+```
+
 ---
 
 ## Tenant / Team Provisioning

docs/configuration.md

@@ -198,7 +198,52 @@ Secret key for signing MFA JWTs. Falls back to `APP_KEY` if not set.
 'url_expiry_time' => 60,
 ```
 
-Minutes before magic links and password reset links expire.
+Minutes before password-reset and email-verification links expire. (Magic links
+use their own `magic_link.expires_in` — see [Magic Link](#magic-link) below.)
+
+### Magic Link
+
+Stateful, single-use passwordless login. See
+[authentication.md](./authentication.md#magic-link-authentication) for the flow.
+
+```php
+'magic_link' => [
+    // Minutes a link stays valid (recommended 5–15).
+    'expires_in' => env('NEEV_MAGIC_LINK_EXPIRY', 10),
+
+    // Restrict redemption to the browser/device that requested it.
+    'bind_to_browser' => false,
+
+    // Require an explicit confirm step before consuming (defeats email scanners).
+    'require_confirmation' => false,
+
+    // Channel-aware URL building. Add your own channels (e.g. 'desktop') here
+    // with no code change. A channel with a 'scheme'/'universal_link' is built
+    // as a deep link; otherwise a web URL from 'base_url' + 'path'.
+    'channels' => [
+        'web' => [
+            'base_url' => env('APP_URL'),   // point at your frontend for a decoupled SPA
+            'path' => '/login-link',
+        ],
+        'mobile' => [
+            'scheme' => env('NEEV_MOBILE_SCHEME'),           // e.g. myapp://login
+            'universal_link' => env('NEEV_MOBILE_UNIVERSAL_LINK'),
+        ],
+    ],
+],
+```
+
+| Key | Default | Purpose |
+|---|---|---|
+| `expires_in` | `10` | Minutes a link is valid. |
+| `bind_to_browser` | `false` | Only redeem from the originating browser/device. |
+| `require_confirmation` | `false` | Add an explicit confirm step. |
+| `channels` | web + mobile | Per-channel URL building (extensible). |
+
+Notes:
+- Tokens are single-use (deleted on redemption); a new link invalidates the previous one.
+- A magic link does **not** enforce MFA (by design).
+- Prune expired rows with `php artisan neev:clean-magic-links`.
 
 ### OTP Expiry
 

docs/db-schema.dbml

@@ -248,5 +248,24 @@ Table tenant_auth_settings {
   updated_at timestamp
 }
 
+Table magic_link_tokens {
+  id bigint [pk, increment]
+  user_id bigint [ref: > users.id]
+  tenant_id bigint [null, ref: > tenants.id]
+  token varchar [unique, note: 'SHA-256 hash of the opaque token']
+  channel varchar [default: 'web', note: 'web / mobile / custom']
+  meta_data varchar [null, note: 'JSON; holds the browser/device binding fingerprint']
+  user_agent text [null]
+  created_ip varchar [null]
+  expires_at timestamp
+  created_at timestamp
+  updated_at timestamp
+
+  indexes {
+    user_id
+    (user_id, channel)
+  }
+}
+
 // Cross-table refs that can't be inline
 Ref: users.default_team_id > teams.id

docs/spa-authentication.md

@@ -256,10 +256,13 @@ POST /neev/sendLoginLink
 { "message": "Login link has been sent." }
 ```
 
-The emailed link points at your frontend (`{APP_URL}/login-link?id=…&signature=…&expires=…`). Your SPA route at `/login-link` forwards the query string to the API **via XHR** (the XHR carries your stateful `Origin`, which is what triggers the cookie):
+The emailed link points at your frontend (`{base_url}/login-link?token=…`, where
+`base_url` is `magic_link.channels.web.base_url` — set it to your frontend origin).
+Your SPA route at `/login-link` forwards the opaque `token` to the API **via XHR**
+(the XHR carries your stateful `Origin`, which is what triggers the cookie):
 
 ```http
-GET /neev/loginUsingLink?id={id}&expires={timestamp}&signature={signature}
+GET /neev/loginUsingLink?token={token}
 ```
 
 **Response** — cookie set:

docs/web-routes.md

@@ -41,8 +41,12 @@ These routes are accessible without authentication.
 
 | Method | Route | Name | Description |
 |--------|-------|------|-------------|
-| POST | `/login/link` | `login.link.send` | Send login link to email |
-| GET | `/login/{id}` | `login.link` | Login via magic link |
+| POST | `/login/link` | `login.link.send` | Send a single-use login link to email |
+| GET / POST | `/login-link/verify` | `login.link.verify` | Redeem the link (GET opens; POST confirms) |
+
+The link is single-use and redeemed via `token`. When
+`magic_link.require_confirmation` is enabled, the `GET` shows a confirmation page
+and the user's `POST` completes the login (see [authentication.md](./authentication.md#magic-link-authentication)).
 
 ---