[imanimanyara]

Summary

A provider package had no way to attach a sign-in method to an account except by inferring consent
from the fact that somebody was logged in. This adds the explicit mechanism: IdentityLinkingInterface,
bound to Services\IdentityLinking.

$token = $linking->issueIntent($request, $request->user(), 'web', 'github');
// ... carry $token through the provider redirect, and on the way back:
$linking->consumeIntent($request, $token, $request->user(), 'web', 'github');
$linking->assertLinkable($request->user(), $ownerOfThisExternalIdentity);
// only now does the provider package write the link

AuthKit owns whether a link is allowed. The provider package owns where links are stored and who
currently holds an identity, because it owns the table.

Why linking is not sign-in

Resolving an account from a verified address is how a provider signs you in. It is not good enough
to attach a standing new credential, because the two have different blast radii: a wrong sign-in
ends with a session, a wrong link ends with a way back in that the owner never chose.

The separation is structural, not a convention anyone has to remember:

• Nothing here can authenticate. No access to a guard's login; every method returns a value
  object or nothing. A test asserts nobody is signed in after a link completes.
• Nothing here takes an email address. No parameter, no field on LinkIntent. "Do not treat a
  matching email as authorization" is a property of the shape, so a reflection test asserts the
  shape rather than a branch — a branch can drift, a missing parameter cannot.

The four security requirements, and where each lands

Requirement	How
Bind the attempt to the initiating user and auth context; single-use state	256-bit token stored only as its SHA-256; the record binds user, model class, guard, provider and a hash of the session or access token, all re-compared on the way back. Spending is read-and-delete under an atomic lock where the store offers one
Require recent reauthentication with an available credential	auth.password_confirmed_at against auth.password_timeout for a session — exactly what Laravel's password.confirm maintains — or a password proved on the request for a token client, checked through the guard's own provider
Reject an identity linked to another user; never switch or transfer	assertLinkable returns for a free identity, is idempotent for one this user already owns, and otherwise throws. The only outcomes are allowed and an exception
Never treat a matching email as authorization	The surface has nowhere to put one

Refusals carry a closed IdentityLinkFailure enum rather than a message, so a web flow redirecting
to password confirmation and an API returning 403 can handle the same refusal differently without
parsing prose.

Verification

Suite	98 passed, 223 assertions (17 new)
laranail-pint --test	passed
Coverage asked for by the issue	state replay, linking to the wrong user, identity conflicts, successful linking — all present

Proven red before being relied on, four separate ways:

Break	Result
Drop the recent-authentication requirement	3 failed
Read the intent without spending it	replay case failed
Stop binding the intent to user, context and provider	3 failed
Permit an identity another user owns	1 failed
Restore	17 passed

One of those checks initially reported a false clean: the script's anchor matched twice, so its
edit never applied and the suite stayed green. It is recorded here because the green was my
script not running, not the guard lacking teeth — the corrected run is the row above.

Not in this change

authkit-social-login still resolves identities the old way, and adopting this mechanism there is
authkit-social-login#12.

Reviewing that package raised a separate concern in its existing resolution path. It is not
described here, because that package is public and the concern is unfixed; it has been reported to
the maintainer privately.

Closes #64.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.