适配器

适配器是一個具有函數屬性（方法）的物件，用於從資料來源讀取和寫入資料。將這些方法視為將資料層標準化為 Auth.js 可以理解的通用介面的方式。

這使得 Auth.js 非常靈活，並允許它與任何資料層一起使用。

适配器方法用於執行以下操作

建立/更新/刪除使用者
將帳戶連結/取消連結到/從使用者
處理活動的工作階段
支援跨多個裝置的無密碼驗證

如果未實作任何方法，但 Auth.js 呼叫了這些方法，則會向使用者顯示錯誤，且作業將失敗。

方法

createAuthenticator()?

optional createAuthenticator(authenticator): Awaitable<AdapterAuthenticator>

建立新的驗證器。

如果建立失敗，适配器必須擲回錯誤。

參數

參數	類型
`authenticator`	`AdapterAuthenticator`

回傳值

Awaitable<AdapterAuthenticator>

createSession()?

optional createSession(session): Awaitable<AdapterSession>

為使用者建立工作階段並傳回該工作階段。

另請參閱資料庫工作階段管理

參數

參數	類型
`session`	`物件`
`session.expires`	`日期`
`session.sessionToken`	`字串`
`session.userId`	`字串`

回傳值

Awaitable<AdapterSession>

createUser()?

optional createUser(user): Awaitable<AdapterUser>

在資料庫中建立使用者並傳回該使用者。

另請參閱使用者管理

參數

參數	類型
`user`	`AdapterUser`

回傳值

Awaitable<AdapterUser>

createVerificationToken()?

optional createVerificationToken(verificationToken): Awaitable<undefined | null | VerificationToken>

建立驗證權杖並傳回該權杖。

另請參閱驗證權杖

參數

參數	類型
`verificationToken`	`VerificationToken`

回傳值

Awaitable<undefined | null | VerificationToken>

deleteSession()?

optional deleteSession(sessionToken): Promise<void> | Awaitable<undefined | null | AdapterSession>

從資料庫刪除工作階段。最好此方法也傳回為了記錄目的而刪除的工作階段。

另請參閱資料庫工作階段管理

參數

參數	類型
`sessionToken`	`字串`

回傳值

Promise<void> | Awaitable<undefined | null | AdapterSession>

deleteUser()?

optional deleteUser(userId): Promise<void> | Awaitable<undefined | null | AdapterUser>

參數

參數	類型
`userId`	`字串`

回傳

Promise<void> | Awaitable<undefined | null | AdapterUser>

待辦事項

此方法目前尚未被調用。

另請參閱使用者管理

getAccount()?

optional getAccount(providerAccountId, provider): Awaitable<null | AdapterAccount>

依供應商帳戶 ID 和供應商取得帳戶。

如果找不到帳戶，適配器必須回傳 null。

參數

參數	類型
`providerAccountId`	`字串`
`provider`	`字串`

回傳

Awaitable<null | AdapterAccount>

getAuthenticator()?

optional getAuthenticator(credentialID): Awaitable<null | AdapterAuthenticator>

從憑證 ID 回傳驗證器。

如果找不到驗證器，適配器必須回傳 null。

參數

參數	類型
`credentialID`	`字串`

回傳

Awaitable<null | AdapterAuthenticator>

getSessionAndUser()?

optional getSessionAndUser(sessionToken): Awaitable<null | {
  session: AdapterSession;
  user: AdapterUser;
}>

一次從資料庫中回傳 session 和 user。

💡

如果資料庫支援聯結，建議減少資料庫查詢的次數。

另請參閱資料庫工作階段管理

參數

參數	類型
`sessionToken`	`字串`

回傳

Awaitable<null | { session: AdapterSession; user: AdapterUser; }>

getUser()?

optional getUser(id): Awaitable<null | AdapterUser>

透過使用者 ID 從資料庫回傳使用者。

另請參閱使用者管理

參數

參數	類型
`id`	`字串`

回傳

Awaitable<null | AdapterUser>

getUserByAccount()?

optional getUserByAccount(providerAccountId): Awaitable<null | AdapterUser>

使用供應商 ID 和特定帳戶的使用者 ID，取得使用者。

另請參閱使用者管理

參數

參數	類型
`providerAccountId`	`Pick`<`AdapterAccount`, `"provider"` \| `"providerAccountId"`>

回傳

Awaitable<null | AdapterUser>

getUserByEmail()?

optional getUserByEmail(email): Awaitable<null | AdapterUser>

透過使用者的電子郵件地址從資料庫回傳使用者。

另請參閱驗證權杖

參數

參數	類型
`email`	`字串`

回傳

Awaitable<null | AdapterUser>

linkAccount()?

optional linkAccount(account): Promise<void> | Awaitable<undefined | null | AdapterAccount>

此方法會在內部調用（但可選擇用於手動連結）。它會在資料庫中建立一個帳戶。

另請參閱使用者管理

參數

參數	類型
`account`	`AdapterAccount`

回傳

Promise<void> | Awaitable<undefined | null | AdapterAccount>

listAuthenticatorsByUserId()?

optional listAuthenticatorsByUserId(userId): Awaitable<AdapterAuthenticator[]>

回傳使用者所有的驗證器。

如果找不到使用者，適配器仍應回傳一個空陣列。如果因其他原因擷取失敗，適配器必須拋出錯誤。

參數

參數	類型
`userId`	`字串`

回傳

Awaitable<AdapterAuthenticator[]>

unlinkAccount()?

optional unlinkAccount(providerAccountId): Promise<void> | Awaitable<undefined | AdapterAccount>

參數

參數	類型
`providerAccountId`	`Pick`<`AdapterAccount`, `"provider"` \| `"providerAccountId"`>

回傳

Promise<void> | Awaitable<undefined | AdapterAccount>

待辦事項

此方法目前尚未被調用。

updateAuthenticatorCounter()?

optional updateAuthenticatorCounter(credentialID, newCounter): Awaitable<AdapterAuthenticator>

更新驗證器的計數器。

如果更新失敗，適配器必須拋出錯誤。

參數

參數	類型
`credentialID`	`字串`
`newCounter`	`number`

回傳

Awaitable<AdapterAuthenticator>

updateSession()?

optional updateSession(session): Awaitable<undefined | null | AdapterSession>

更新資料庫中的 session 並回傳。

另請參閱資料庫工作階段管理

參數

參數	類型
`session`	`Partial`<`AdapterSession`> & `Pick`<`AdapterSession`, `"sessionToken"`>

回傳

Awaitable<undefined | null | AdapterSession>

updateUser()?

optional updateUser(user): Awaitable<AdapterUser>

更新資料庫中的使用者並回傳。

另請參閱使用者管理

參數

參數	類型
`user`	`Partial`<`AdapterUser`> & `Pick`<`AdapterUser`, `"id"`>

回傳

Awaitable<AdapterUser>

useVerificationToken()?

optional useVerificationToken(params): Awaitable<null | VerificationToken>

從資料庫回傳驗證權杖並將其刪除，以便只能使用一次。

另請參閱驗證權杖

參數

參數	類型
`params`	`物件`
`params.identifier`	`字串`
`params.token`	`字串`

回傳

Awaitable<null | VerificationToken>

AdapterAccount

帳戶是使用者和供應商之間的連線。

帳戶有兩種型態

OAuth/OIDC 帳戶，是在使用者使用 OAuth 供應商登入時建立的。
電子郵件帳戶，是在使用者使用電子郵件供應商登入時建立的。

一個使用者可以擁有多個帳戶。

延伸

帳戶

屬性

access_token?

optional readonly access_token: string;

繼承自

Account.access_token

authorization_details?

optional readonly authorization_details: AuthorizationDetails[];

繼承自

Account.authorization_details

expires_at?

optional expires_at: number;

基於 TokenEndpointResponse.expires_in 計算的值。

這是 TokenEndpointResponse.access_token 過期的絕對時間戳記（以秒為單位）。

此值可用於與 TokenEndpointResponse.refresh_token 一起實作令牌輪換。

參見

繼承自

Account.expires_at

expires_in?

optional readonly expires_in: number;

繼承自

Account.expires_in

id_token?

optional readonly id_token: string;

繼承自

Account.id_token

provider

provider: string;

此帳戶的供應商 ID。例如：「google」。請參閱完整列表：https://authjs.dev.org.tw/reference/core/providers

繼承自

Account.provider

providerAccountId

providerAccountId: string;

此值取決於用於建立帳戶的供應商類型。

oauth/oidc：OAuth 帳戶的 ID，從 profile() 回呼傳回。
email：使用者的電子郵件地址。
credentials：從 authorize() 回呼傳回的 id

繼承自

Account.providerAccountId

refresh_token?

optional readonly refresh_token: string;

繼承自

Account.refresh_token

scope?

optional readonly scope: string;

繼承自

Account.scope

token_type?

optional readonly token_type: Lowercase<string>;

注意：由於該值不區分大小寫，因此始終以小寫形式傳回

繼承自

Account.token_type

type

type: AdapterAccountType;

此帳戶的供應商類型

覆寫

Account.type

userId

userId: string;

此帳戶所屬使用者的 ID

參見

https://authjs.dev.org.tw/reference/core/adapters#adapteruser

覆寫

Account.userId

AdapterAuthenticator

驗證器代表指派給使用者的憑證驗證器。

擴展

Authenticator

屬性

counter

counter: number;

驗證器已使用的次數。

繼承自

Authenticator.counter

credentialBackedUp

credentialBackedUp: boolean;

用戶端驗證器是否備份了憑證。

繼承自

Authenticator.credentialBackedUp

credentialDeviceType

credentialDeviceType: string;

驗證器的裝置類型。

繼承自

Authenticator.credentialDeviceType

credentialID

credentialID: string;

Base64 編碼的憑證 ID。

繼承自

Authenticator.credentialID

credentialPublicKey

credentialPublicKey: string;

Base64 編碼的憑證公開金鑰。

繼承自

Authenticator.credentialPublicKey

providerAccountId

providerAccountId: string;

連接到驗證器的供應商帳戶 ID。

繼承自

Authenticator.providerAccountId

transports?

optional transports: null | string;

串連的傳輸旗標。

繼承自

Authenticator.transports

userId

userId: string;

驗證器的使用者 ID。

覆寫

Authenticator.userId

AdapterSession

工作階段保存使用者目前登入狀態的相關資訊。

屬性

expires

expires: Date;

工作階段過期的絕對日期。

如果在到期日期之前存取工作階段，則會根據 SessionOptions.maxAge 中定義的 maxAge 選項延長工作階段。在 SessionOptions.updateAge 定義的期間內，工作階段絕不會延長超過一次。

如果工作階段在其到期日期之後被存取，則會將其從資料庫中移除，以清除非作用中的工作階段。

sessionToken

sessionToken: string;

一個隨機產生的值，當使用 "database" AuthConfig.strategy 選項時，用於在資料庫中查找會話。這個值會以安全、HTTP-Only 的 cookie 儲存在用戶端。

userId

userId: string;

將活動中的會話連接到資料庫中的使用者。

AdapterUser

使用者代表可以登入應用程式的人。如果使用者尚不存在，則會在他們第一次登入時使用身分提供者返回的資訊（個人資料）建立使用者。同時也會建立一個對應的帳戶並連結到該使用者。

繼承

User

屬性

email

email: string;

使用者的電子郵件地址。

覆寫

User.email

emailVerified

emailVerified: null | Date;

使用者是否已通過電子郵件提供者驗證其電子郵件地址。如果使用者尚未通過電子郵件提供者登入，則為 null ，否則為第一次成功登入的日期。

id

id: string;

使用者的唯一識別碼。

覆寫

User.id

image?

optional image: null | string;

繼承自

User.image

name?

optional name: null | string;

繼承自

User.name

VerificationToken

驗證令牌是用於通過電子郵件地址登入使用者的臨時令牌。當使用者使用電子郵件提供者登入時會建立該令牌。當使用者點擊電子郵件中的連結時，令牌和電子郵件會被發回伺服器，經過雜湊處理後與資料庫中的值進行比較。如果令牌和電子郵件匹配，且令牌尚未過期，則使用者會被登入。然後令牌會從資料庫中刪除。

屬性

expires

expires: Date;

令牌過期的絕對日期。

identifier

identifier: string;

使用者的電子郵件地址。

token

token: string;

使用 AuthConfig.secret 值進行雜湊處理的令牌。

AdapterAccountType

type AdapterAccountType: Extract<ProviderType, "oauth" | "oidc" | "email" | "webauthn">;

帳戶的類型。

isDate()

isDate(value): value is string

判斷給定的值是否可以解析為 Date。

參數

參數	類型
`value`	`unknown`

value is string

@auth/express lib