Skip to main content
zerotal

Documentation

Documentation / @zerotal/auth / MagicLinkBroker

Class: MagicLinkBroker<U>

Defined in: auth/src/MagicLinkBroker.ts:74

Passwordless "magic link" login broker.

Remarks

sendLink mints a signed, expiring URL (via Url.sign, keyed by secret) that embeds the target email and points at your verify endpoint, then hands it to your sendLink callback to deliver. Guard that endpoint with ValidateSignatureMiddleware so a tampered or expired link is rejected before your handler runs; call login once the signature is confirmed to regenerate the session and sign the user in. The signature carries no server-side state, so it is not single-use on its own — it stays valid until it expires.

Example

const magicLinks = new MagicLinkBroker({
  secret: config("app.key"),
  verifyUrl: "https://example.com/auth/magic/verify",
  findUser: (email) => User.query().where("email", email).first(),
  sendLink: (email, url) => Mail.to(email).send(new MagicLink(url)),
});

await magicLinks.sendLink("a@b.com");     // MAGIC.SENT or MAGIC.USER_NOT_FOUND
// …at the (signature-validated) verify endpoint:
await magicLinks.login("a@b.com", ctx);   // MAGIC.OK or MAGIC.INVALID

Type Parameters

U

U extends MagicLinkUser = MagicLinkUser

Constructors

Constructor

new MagicLinkBroker<U>(opts): MagicLinkBroker<U>

Defined in: auth/src/MagicLinkBroker.ts:77

Parameters

opts

MagicLinkBrokerOptions<U>

Returns

MagicLinkBroker<U>

Methods

sendLink(email): Promise<"magic.sent" | "magic.user_not_found">

Defined in: auth/src/MagicLinkBroker.ts:87

Generate a signed magic link and send it to the user.

Parameters

email

string

The address to look up and deliver the link to.

Returns

Promise<"magic.sent" | "magic.user_not_found">

MAGIC.SENT on success, MAGIC.USER_NOT_FOUND if no user exists.

login()

login(email, ctx): Promise<"magic.ok" | "magic.invalid">

Defined in: auth/src/MagicLinkBroker.ts:114

Establish a session for the link's email, regenerating the session id first.

Parameters

email

string

The email carried by the (validated) signed link.

ctx

HttpContext

The request context whose session is regenerated and populated.

Returns

Promise<"magic.ok" | "magic.invalid">

MAGIC.OK on success, MAGIC.INVALID if the user no longer exists.

Remarks

Assumes the URL signature has already been validated (e.g. by ValidateSignatureMiddleware); this method only re-checks that the user still exists and then seeds the session.

verify()

verify(signedUrl): boolean

Defined in: auth/src/MagicLinkBroker.ts:135

Manually verify a signed URL string (without middleware).

Parameters

signedUrl

string

The full signed URL to check.

Returns

boolean

true when the signature is intact and unexpired.