Repository Interfaces

Auth Code Repository

OAuthAuthCodeRepository interface is utilized for managing OAuth authorization codes. It contains methods for retrieving an authorization code entity by its identifier, issuing a new authorization code, persisting an authorization code in the storage, checking if an authorization code has been revoked, and revoking an authorization code.

Used in Grants: Authorization Code

interface OAuthAuthCodeRepository {
  // Fetch auth code entity from storage by code
  getByIdentifier(authCodeCode: string): Promise<OAuthAuthCode>;

  // An async call that should return an OAuthAuthCode that has not been
  // persisted to storage yet.
  issueAuthCode(
    client: OAuthClient,
    user: OAuthUser | undefined,
    scopes: OAuthScope[],
  ): OAuthAuthCode | Promise<OAuthAuthCode>;

  // An async call that should persist an OAuthAuthCode into your storage.
  persist(authCode: OAuthAuthCode): Promise<void>;

  // This async method is called when an auth code is validated by the
  // authorization server. Return `true` if the auth code has been
  // manually revoked. If the code is still valid return `false`
  isRevoked(authCodeCode: string): Promise<boolean>;

  revoke(authCodeCode: string): Promise<void>;
}

Client Repository

OAuthClientRepository interface is used for managing OAuth clients. It includes methods for fetching a client entity from storage by the client ID and for validating the client using the grant type and client secret.

Used in Grants: Authorization CodeClient CredentialsRefresh TokenPasswordImplicitCustom

interface OAuthClientRepository {
  // Fetch client entity from storage by client_id
  getByIdentifier(clientId: string): Promise<OAuthClient>;

  // check the grant type and secret against the client
  isClientValid(
    grantType: GrantIdentifier,
    client: OAuthClient,
    clientSecret?: string,
  ): Promise<boolean>;
}

Scope Repository

The OAuthScopeRepository interface handles scope management. It defines methods for finding all scopes by their names and for finalizing the scopes. In the finalization, additional scopes can be added or removed after they've been validated against the client scopes.

Used in Grants: Authorization CodeClient CredentialsRefresh TokenPasswordImplicitCustom

interface OAuthScopeRepository {
  // Find all scopes by scope names
  getAllByIdentifiers(scopeNames: string[]): Promise<OAuthScope[]>;

  // Scopes have already been validated against the client, if you arent
  // doing anything fancy with scopes, you can just `return scopes`,
  // Otherwise, now is your chance to add or remove any final scopes
  // after they have already been validated against the client scopes
  finalize(
    scopes: OAuthScope[],
    identifier: GrantIdentifier,
    client: OAuthClient,
    user_id?: string,
  ): Promise<OAuthScope[]>;
}

Token Repository

OAuthTokenRepository interface manages OAuth tokens. It contains methods for issuing a new token, persisting a token in the storage, issuing a refresh token, revoking tokens, and fetching a refresh token entity by the refresh token.

Used in Grants: Authorization CodeClient CredentialsRefresh TokenPasswordImplicitCustom

interface OAuthTokenRepository {
  // An async call that should return an OAuthToken that has not been
  // persisted to storage yet.
  issueToken(client: OAuthClient, scopes: OAuthScope[], user?: OAuthUser): Promise<OAuthToken>;

  // An async call that should persist an OAuthToken into your storage.
  persist(accessToken: OAuthToken): Promise<void>;

  // An async call that enhances an already-persisted OAuthToken with
  // refresh token fields.
  issueRefreshToken(accessToken: OAuthToken, client: OAuthClient): Promise<OAuthToken>;

  // This async method is called when a refresh token is used to reissue
  // an access token. The original access token is revoked, and a new
  // access token is issued.
  revoke(accessToken: OAuthToken): Promise<void>;

  // This async method, if implemented, will be called by the authorization
  // code grant if the original authorization code is reused.
  // See https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2 for why.
  revokeDescendantsOf?(authCodeId: string): Promise<void>;

  // This async method is called when an access token is validated by the
  // authorization server. Return `true` if the access token has been
  // manually revoked. If the token is still valid return `false`
  isRefreshTokenRevoked(refreshToken: OAuthToken): Promise<boolean>;

  // Fetch refresh token entity from storage by refresh token
  getByRefreshToken(refreshTokenToken: string): Promise<OAuthToken>;

  // (Optional)
  //     Required if using /revoke RFC7009 "OAuth 2.0 Token Revocation"
  //     Required if using /introspect RFC7662 "OAuth 2.0 Token Introspection"
  // @see https://tsoauth2server.com/docs/getting_started/endpoints#the-introspect-endpoint
  // @see https://tsoauth2server.com/docs/getting_started/endpoints#the-revoke-endpoint
  getByAccessToken?(accessTokenToken: string): Promise<OAuthToken>;
}

User Repository

The OAuthUserRepository interface handles user management. It defines methods for fetching a user entity from storage by their credentials and optional grant type and client. This may involve validating the user's credentials.

Used in Grants: Authorization CodePassword

interface OAuthUserRepository {
  // Fetch user entity from storage by identifier. A provided password may
  // be used to validate the users credentials. Grant type and client are provided
  // for additional checks if desired
  getUserByCredentials(
    identifier: string,
    password?: string,
    grantType?: GrantIdentifier,
    client?: OAuthClient,
  ): Promise<OAuthUser | undefined>;
}