@atproto/oauth-provider 0.18.4 → 0.19.0

package/src/account/account-manager.ts

@@ -1,3 +1,4 @@
+import { Did } from '@atproto/did'
 import {
   OAuthIssuerIdentifier,
   isOAuthClientIdLoopback,
@@ -12,11 +13,12 @@ import { callAsync } from '../lib/util/function.js'
 import { constantTime } from '../lib/util/time.js'
 import { OAuthHooks, RequestMetadata } from '../oauth-hooks.js'
 import { Customization } from '../oauth-provider.js'
-import { Sub } from '../oidc/sub.js'
 import {
   Account,
   AccountStore,
   AuthorizedClientData,
+  DeleteAccountConfirmInput,
+  DeleteAccountRequestInput,
   DeviceAccount,
   ResetPasswordConfirmInput,
   ResetPasswordRequestInput,
@@ -152,7 +154,7 @@ export class AccountManager {
 
         return account
       } catch (err) {
-        await this.removeDeviceAccount(deviceId, account.sub)
+        await this.removeDeviceAccount(deviceId, account.did)
 
         throw InvalidRequestError.from(
           err,
@@ -190,7 +192,7 @@ export class AccountManager {
           // This information is only exposed to the hook and is never
           // surfaced to the client.
           const isCredentialsError = err instanceof InvalidCredentialsError
-          const sub = isCredentialsError ? err.sub ?? null : null
+          const did = isCredentialsError ? err.did ?? null : null
 
           // Swallow any error from the hook itself so that it does not mask
           // the underlying authentication failure being reported.
@@ -198,7 +200,7 @@ export class AccountManager {
             await this.hooks.onSignInFailed?.call(null, {
               data,
               error: err,
-              sub,
+              did,
               deviceId,
               deviceMetadata,
               clientId,
@@ -235,16 +237,16 @@ export class AccountManager {
 
   public async upsertDeviceAccount(
     deviceId: DeviceId,
-    sub: Sub,
+    did: Did,
   ): Promise<void> {
-    await this.store.upsertDeviceAccount(deviceId, sub)
+    await this.store.upsertDeviceAccount(deviceId, did)
   }
 
   public async getDeviceAccount(
     deviceId: DeviceId,
-    sub: Sub,
+    did: Did,
   ): Promise<DeviceAccount> {
-    const deviceAccount = await this.store.getDeviceAccount(deviceId, sub)
+    const deviceAccount = await this.store.getDeviceAccount(deviceId, did)
     if (!deviceAccount) throw new InvalidRequestError(`Account not found`)
 
     return deviceAccount
@@ -258,15 +260,15 @@ export class AccountManager {
     // "Loopback" clients are not distinguishable from one another.
     if (isOAuthClientIdLoopback(client.id)) return
 
-    await this.store.setAuthorizedClient(account.sub, client.id, data)
+    await this.store.setAuthorizedClient(account.did, client.id, data)
   }
 
-  public async getAccount(sub: Sub) {
-    return this.store.getAccount(sub)
+  public async getAccount(did: Did) {
+    return this.store.getAccount(did)
   }
 
-  public async removeDeviceAccount(deviceId: DeviceId, sub: Sub) {
-    return this.store.removeDeviceAccount(deviceId, sub)
+  public async removeDeviceAccount(deviceId: DeviceId, did: Did) {
+    return this.store.removeDeviceAccount(deviceId, did)
   }
 
   public async listDeviceAccounts(
@@ -280,13 +282,13 @@ export class AccountManager {
       .filter((deviceAccount) => deviceAccount.deviceId === deviceId)
   }
 
-  public async listAccountDevices(sub: Sub): Promise<DeviceAccount[]> {
+  public async listAccountDevices(did: Did): Promise<DeviceAccount[]> {
     const deviceAccounts = await this.store.listDeviceAccounts({
-      sub,
+      did,
     })
 
     return deviceAccounts // Fool proof
-      .filter((deviceAccount) => deviceAccount.account.sub === sub)
+      .filter((deviceAccount) => deviceAccount.account.did === did)
   }
 
   public async resetPasswordRequest(
@@ -412,8 +414,8 @@ export class AccountManager {
     await this.hooks.onVerifyEmailRequest?.call(null, {
       deviceId,
       deviceMetadata,
-      input,
       account,
+      input,
     })
 
     await this.store.verifyEmailRequest(input)
@@ -421,8 +423,8 @@ export class AccountManager {
     await this.hooks.onVerifyEmailRequested?.call(null, {
       deviceId,
       deviceMetadata,
-      input,
       account,
+      input,
     })
   }
 
@@ -435,8 +437,8 @@ export class AccountManager {
     await this.hooks.onVerifyEmailConfirm?.call(null, {
       deviceId,
       deviceMetadata,
-      input,
       account,
+      input,
     })
 
     const updatedAccount = await this.store.verifyEmailConfirm(input)
@@ -448,8 +450,8 @@ export class AccountManager {
     await this.hooks.onVerifyEmailConfirmed?.call(null, {
       deviceId,
       deviceMetadata,
-      input,
       account: updatedAccount,
+      input,
     })
 
     return updatedAccount
@@ -479,4 +481,105 @@ export class AccountManager {
 
     return updatedAccount
   }
+
+  public async deactivateAccount(
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+    account: Account,
+  ): Promise<Account> {
+    await this.hooks.onDeactivateAccount?.call(null, {
+      deviceId,
+      deviceMetadata,
+      account,
+    })
+
+    const updatedAccount = await callAsync(() =>
+      this.store.deactivateAccount({ did: account.did }),
+    ).catch((err) => {
+      throw InvalidRequestError.from(err, 'Account deactivation failed')
+    })
+
+    await this.hooks.onDeactivatedAccount?.call(null, {
+      deviceId,
+      deviceMetadata,
+      account: updatedAccount,
+    })
+
+    return updatedAccount
+  }
+
+  public async reactivateAccount(
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+    account: Account,
+  ): Promise<Account> {
+    await this.hooks.onReactivateAccount?.call(null, {
+      deviceId,
+      deviceMetadata,
+      account,
+    })
+
+    const updatedAccount = await callAsync(() =>
+      this.store.reactivateAccount({ did: account.did }),
+    ).catch((err) => {
+      throw InvalidRequestError.from(err, 'Account reactivation failed')
+    })
+
+    await this.hooks.onReactivatedAccount?.call(null, {
+      deviceId,
+      deviceMetadata,
+      account: updatedAccount,
+    })
+
+    return updatedAccount
+  }
+
+  public async deleteAccountRequest(
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+    input: DeleteAccountRequestInput,
+    account: Account,
+  ): Promise<void> {
+    await this.hooks.onDeleteAccountRequest?.call(null, {
+      deviceId,
+      deviceMetadata,
+      account,
+    })
+
+    await this.store.deleteAccountRequest(input)
+
+    await this.hooks.onDeleteAccountRequested?.call(null, {
+      deviceId,
+      deviceMetadata,
+      account,
+    })
+  }
+
+  public async deleteAccountConfirm(
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+    input: DeleteAccountConfirmInput,
+    account: Account,
+  ): Promise<void> {
+    return constantTime(BRUTE_FORCE_MITIGATION_DELAY, async () => {
+      await this.hooks.onDeleteAccountConfirm?.call(null, {
+        deviceId,
+        deviceMetadata,
+        account,
+      })
+
+      await callAsync(() => this.store.deleteAccountConfirm(input)).catch(
+        (err) => {
+          throw InvalidRequestError.from(err, 'Account deletion failed')
+        },
+      )
+
+      await this.hooks.onDeleteAccountConfirmed?.call(null, {
+        deviceId,
+        deviceMetadata,
+        account,
+        input,
+      })
+    })
+  }
 }

package/src/account/account-store.ts

@@ -1,12 +1,17 @@
+import { Did } from '@atproto/did'
 import type {
   Account,
+  ConfirmAccountDeletionInput,
   ConfirmEmailUpdateInput,
   ConfirmEmailVerificationInput,
   ConfirmResetPasswordInput,
+  DeactivateAccountInput,
+  InitiateAccountDeletionInput,
   InitiateEmailUpdateInput,
   InitiateEmailUpdateOutput,
   InitiateEmailVerificationInput,
   InitiatePasswordResetInput,
+  ReactivateAccountInput,
   UpdateHandleInput,
 } from '@atproto/oauth-provider-api'
 import { OAuthScope } from '@atproto/oauth-types'
@@ -21,7 +26,6 @@ import {
   InvalidRequestError,
   SecondAuthenticationFactorRequiredError,
 } from '../oauth-errors.js'
-import { Sub } from '../oidc/sub.js'
 import { InviteCode } from '../types/invite-code.js'
 import { SignUpInput } from './sign-up-input.js'
 
@@ -30,11 +34,11 @@ import { SignUpInput } from './sign-up-input.js'
 export * from '../client/client-id.js'
 export * from '../device/device-data.js'
 export * from '../device/device-id.js'
-export * from '../oidc/sub.js'
 export * from '../request/request-id.js'
 
 export type {
   Account,
+  Did,
   HcaptchaVerifyResult,
   InviteCode,
   OAuthScope,
@@ -58,6 +62,11 @@ export type VerifyEmailRequestInput = InitiateEmailVerificationInput
 export type VerifyEmailConfirmInput = ConfirmEmailVerificationInput
 export type UpdateHandleData = UpdateHandleInput
 
+export type DeactivateAccountData = DeactivateAccountInput
+export type ReactivateAccountData = ReactivateAccountInput
+export type DeleteAccountRequestInput = InitiateAccountDeletionInput
+export type DeleteAccountConfirmInput = ConfirmAccountDeletionInput
+
 export type CreateAccountData = {
   locale: string
   email: string
@@ -124,7 +133,7 @@ export interface AccountStore {
 
   /**
    * @throws {InvalidCredentialsError} - When the credentials are not valid.
-   * Populate {@link InvalidCredentialsError.sub} with the subject identifier
+   * Populate {@link InvalidCredentialsError.did} with the subject identifier
    * when the identifier matched an existing account (e.g. wrong password for
    * a known user); omit it when the identifier was not found. Throwing the
    * generic {@link InvalidRequestError} is also accepted for backward
@@ -138,7 +147,7 @@ export interface AccountStore {
    * Add a client & scopes to the list of authorized clients for the given account.
    */
   setAuthorizedClient(
-    sub: Sub,
+    did: Did,
     clientId: ClientId,
     data: AuthorizedClientData,
   ): Awaitable<void>
@@ -146,7 +155,7 @@ export interface AccountStore {
   /**
    * @throws {InvalidRequestError} - When the credentials are not valid
    */
-  getAccount(sub: Sub): Awaitable<{
+  getAccount(did: Did): Awaitable<{
     account: Account
     authorizedClients: AuthorizedClients
   }>
@@ -162,7 +171,7 @@ export interface AccountStore {
    * {@link RequestStore.deleteRequest}), all accounts bound to that request
    * should be deleted as well.
    */
-  upsertDeviceAccount(deviceId: DeviceId, sub: Sub): Awaitable<void>
+  upsertDeviceAccount(deviceId: DeviceId, did: Did): Awaitable<void>
 
   /**
    * @param requestId - If provided, the result must either have the same
@@ -173,7 +182,7 @@ export interface AccountStore {
    */
   getDeviceAccount(
     deviceId: DeviceId,
-    sub: Sub,
+    did: Did,
   ): Awaitable<DeviceAccount | null>
 
   /**
@@ -182,14 +191,14 @@ export interface AccountStore {
    *
    * @note Noop if the device-account is not found.
    */
-  removeDeviceAccount(deviceId: DeviceId, sub: Sub): Awaitable<void>
+  removeDeviceAccount(deviceId: DeviceId, did: Did): Awaitable<void>
 
   /**
    * @returns **all** the device accounts that match the {@link requestId}
    * criteria and given {@link filter}.
    */
   listDeviceAccounts(
-    filter: { sub: Sub } | { deviceId: DeviceId },
+    filter: { did: Did } | { deviceId: DeviceId },
   ): Awaitable<DeviceAccount[]>
 
   resetPasswordRequest(
@@ -206,8 +215,8 @@ export interface AccountStore {
   /**
    * Must trigger a verification email to be sent to the new email address, that
    * will then be confirmed through {@link updateEmailConfirm}. The account's
-   * `email_verified` field is expected to become `false` until the new email is
-   * confirmed.
+   * {@link Account['emailVerified'] emailVerified} field is expected to become
+   * `false` until the new email is confirmed.
    */
   updateEmailConfirm(data: UpdateEmailConfirmInput): Awaitable<Account | null>
 
@@ -225,14 +234,53 @@ export interface AccountStore {
    * cannot be used
    */
   updateHandle(data: UpdateHandleData): Awaitable<Account>
+
+  /**
+   * Mark the account as deactivated. The account remains recoverable. Should
+   * be a no-op when the account is already deactivated.
+   *
+   * @throws {InvalidRequestError} - When the account cannot be deactivated
+   * (e.g. unknown account)
+   */
+  deactivateAccount(data: DeactivateAccountData): Awaitable<Account>
+
+  /**
+   * Reactivate a previously-deactivated account. Should be a no-op when the
+   * account is already active.
+   *
+   * @throws {InvalidRequestError} - When the account cannot be reactivated
+   * (e.g. unknown account)
+   */
+  reactivateAccount(data: ReactivateAccountData): Awaitable<Account>
+
+  /**
+   * Initiate account deletion: typically sends a confirmation token to the
+   * account's email address. The account is NOT deleted until
+   * {@link deleteAccountConfirm} is called with the matching token and the
+   * user's current password.
+   */
+  deleteAccountRequest(data: DeleteAccountRequestInput): Awaitable<void>
+
+  /**
+   * Finalize account deletion. Implementations MUST verify both the email
+   * confirmation `token` issued by {@link deleteAccountRequest} and the user's
+   * current `password` before deleting any data. Deletion is irreversible.
+   *
+   * @throws {InvalidRequestError} - When the token or password is invalid.
+   */
+  deleteAccountConfirm(data: DeleteAccountConfirmInput): Awaitable<void>
 }
 
 export const isAccountStore = buildInterfaceChecker<AccountStore>([
   'authenticateAccount',
   'createAccount',
+  'deactivateAccount',
+  'deleteAccountConfirm',
+  'deleteAccountRequest',
   'getAccount',
   'getDeviceAccount',
   'listDeviceAccounts',
+  'reactivateAccount',
   'removeDeviceAccount',
   'resetPasswordConfirm',
   'resetPasswordRequest',

package/src/errors/invalid-credentials-error.ts

@@ -1,4 +1,4 @@
-import { Sub } from '../oidc/sub.js'
+import { Did } from '@atproto/did'
 import { InvalidRequestError } from './invalid-request-error.js'
 
 /**
@@ -6,22 +6,22 @@ import { InvalidRequestError } from './invalid-request-error.js'
  * that a sign-in attempt was rejected because the provided credentials did not
  * match a known account.
  *
- * Stores should populate {@link InvalidCredentialsError.sub} when the
- * identifier resolved to an existing account but e.g. the password or OTP was
- * incorrect. The identifier-unknown case should leave `sub` unset. This
- * information is surfaced to the `onSignInFailed` hook and never sent back to
- * the client, so populating it does not affect the client-visible response.
+ * Stores should populate {@link did}. when the identifier resolved to an
+ * existing account but e.g. the password or OTP was incorrect. The
+ * identifier-unknown case should leave {@link did} unset. This information is
+ * surfaced to the `onSignInFailed` hook and never sent back to the client, so
+ * populating it does not affect the client-visible response.
  *
  * Only the subject identifier (DID) is carried — not a full `Account` — to
  * avoid embedding PII (email, name, etc.) in an error that may be serialized
  * by loggers or monitoring tools walking the `.cause` chain. Hook consumers
  * that need richer profile info can resolve it from their own account store
- * using `sub`.
+ * using {@link did}.
  */
 export class InvalidCredentialsError extends InvalidRequestError {
   constructor(
     message = 'Invalid identifier or password',
-    public readonly sub?: Sub,
+    public readonly did?: Did,
     cause?: unknown,
   ) {
     super(message, cause)

package/src/lib/util/function.ts

@@ -16,8 +16,8 @@ export async function callAsync<F extends (...args: any[]) => unknown>(
 export async function callAsync<F extends (...args: any[]) => unknown>(
   fn?: F,
   ...args: Parameters<F>
-): Promise<Awaited<ReturnType<F>> | undefined> {
-  return (await fn?.(...args)) as Awaited<ReturnType<F>> | undefined
+): Promise<unknown> {
+  return fn?.(...args)
 }
 
 export function invokeOnce<T extends (this: any, ...a: any[]) => any>(

package/src/oauth-hooks.ts

@@ -1,3 +1,4 @@
+import { Did } from '@atproto/did'
 import { Jwks } from '@atproto/jwk'
 import type { Account } from '@atproto/oauth-provider-api'
 import {
@@ -9,6 +10,7 @@ import {
   OAuthTokenType,
 } from '@atproto/oauth-types'
 import {
+  DeleteAccountConfirmInput,
   ResetPasswordConfirmInput,
   ResetPasswordRequestInput,
   SignUpData,
@@ -38,7 +40,6 @@ import {
 } from './lib/hcaptcha.js'
 import { RequestMetadata } from './lib/http/request.js'
 import { Awaitable, OmitKey } from './lib/util/type.js'
-import { Sub } from './oidc/sub.js'
 import { RequestId } from './request/request-id.js'
 import { AccessTokenPayload } from './signer/access-token-payload.js'
 import { TokenClaims } from './token/token-claims.js'
@@ -55,6 +56,7 @@ export {
   type ClientId,
   type ClientInfo,
   type DeviceId,
+  type Did,
   type DpopProof,
   type HcaptchaClientTokens,
   type HcaptchaConfig,
@@ -75,7 +77,6 @@ export {
   type SignInData,
   type SignUpData,
   type SignUpInput,
-  type Sub,
   type TokenClaims,
   type UpdateHandleData,
 }
@@ -208,6 +209,87 @@ export type OAuthHooks = {
     account: Account
   }) => Awaitable<void>
 
+  /**
+   * This hook is called when a user requests account deactivation, before the
+   * account is deactivated on the account store.
+   */
+  onDeactivateAccount?: (data: {
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called after a user successfully deactivated their account on
+   * the account store.
+   */
+  onDeactivatedAccount?: (data: {
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called when a user requests account reactivation, before the
+   * account is reactivated on the account store.
+   */
+  onReactivateAccount?: (data: {
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called after a user successfully reactivated their account on
+   * the account store.
+   */
+  onReactivatedAccount?: (data: {
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called when a user requests account deletion, before the
+   * confirmation email is dispatched on the account store.
+   */
+  onDeleteAccountRequest?: (data: {
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called after a user has requested account deletion and the
+   * confirmation email has been dispatched.
+   */
+  onDeleteAccountRequested?: (data: {
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called when a user confirms account deletion, before the
+   * account is actually deleted on the account store.
+   */
+  onDeleteAccountConfirm?: (data: {
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called after a user has successfully deleted their account
+   * on the account store.
+   */
+  onDeleteAccountConfirmed?: (data: {
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+    input: DeleteAccountConfirmInput
+  }) => Awaitable<void>
+
   /**
    * This hook is called when a user attempts to sign up, after every validation
    * has passed (including hcaptcha).
@@ -336,7 +418,7 @@ export type OAuthHooks = {
   onSignInFailed?: (data: {
     data: SignInData
     error: InvalidRequestError
-    sub: Sub | null
+    did: Did | null
     deviceId: DeviceId
     deviceMetadata: RequestMetadata
     clientId?: ClientId

package/src/oauth-provider.ts

@@ -642,6 +642,10 @@ export class OAuthProvider extends OAuthVerifier {
         throw new AccountSelectionRequiredError(parameters)
       }
 
+      const ssoSessions = sessions
+        .filter(hasActiveAccount)
+        .filter(matchesHint, parameters)
+
       // prompt=none
       //
       // > The Authorization Server MUST NOT display any authentication or
@@ -653,7 +657,6 @@ export class OAuthProvider extends OAuthVerifier {
       // > Section 3.1.2.6. This can be used as a method to check for existing
       // > authentication and/or consent.
       if (parameters.prompt === 'none') {
-        const ssoSessions = sessions.filter(matchesHint, parameters)
         if (ssoSessions.length > 1) {
           throw new AccountSelectionRequiredError(parameters)
         }
@@ -682,7 +685,6 @@ export class OAuthProvider extends OAuthVerifier {
 
       // Automatic SSO when a hint was provided that matches a single session
       if (parameters.prompt == null && parameters.login_hint != null) {
-        const ssoSessions = sessions.filter(matchesHint, parameters)
         if (ssoSessions.length === 1) {
           const ssoSession = ssoSessions[0]!
           if (!ssoSession.loginRequired && !ssoSession.consentRequired) {
@@ -704,12 +706,14 @@ export class OAuthProvider extends OAuthVerifier {
         client,
         parameters,
         requestUri,
-        sessions,
-        selectedSub:
+        sessions: sessions
+          // Strip un-necessary information (like consentRequired)
+          .map(({ account, loginRequired }) => ({ account, loginRequired })),
+        selectedDid:
           parameters.prompt == null ||
           parameters.prompt === 'login' ||
           parameters.prompt === 'consent'
-            ? sessions.find(matchesHint, parameters)?.account.sub
+            ? sessions.find(matchesHint, parameters)?.account.did
             : undefined,
         permissionSets: await this.lexiconManager
           .getPermissionSetsFromScope(parameters.scope)
@@ -884,9 +888,9 @@ export class OAuthProvider extends OAuthVerifier {
             // As an additional security measure, we also sign the device out,
             // so that the device cannot be used to access the account anymore
             // without a new authentication.
-            const { deviceId, sub } = tokenInfo.data
+            const { deviceId, did } = tokenInfo.data
             if (deviceId) {
-              await this.accountManager.removeDeviceAccount(deviceId, sub)
+              await this.accountManager.removeDeviceAccount(deviceId, did)
             }
           }
         }
@@ -912,7 +916,7 @@ export class OAuthProvider extends OAuthVerifier {
 
     await this.validateCodeGrant(parameters, input)
 
-    const { account } = await this.accountManager.getAccount(data.sub)
+    const { account } = await this.accountManager.getAccount(data.did)
 
     return this.tokenManager.createToken(
       client,
@@ -1098,5 +1102,9 @@ function matchesHint(
   const hint = this.login_hint
   if (!hint) return false
 
-  return account.sub === hint || account.preferred_username === hint
+  return account.did === hint || account.handle === hint
+}
+
+function hasActiveAccount({ account }: { account: Account }): boolean {
+  return !account.deactivated
 }