diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 0000000..260e34a --- /dev/null +++ b/index.d.ts @@ -0,0 +1,476 @@ +// Type definitions for Node OAuth2 Server 4.0 +// Definitions by: Robbie Van Gorkom , +// Charles Irick , +// Daniel Fischer , +// Vitor Santos + +import * as http from 'http'; + +/** + * Represents an OAuth2 server instance. + */ +declare class OAuth2Server { + static OAuth2Server: typeof OAuth2Server; + + /** + * Instantiates OAuth2Server using the supplied model + */ + constructor(options: OAuth2Server.ServerOptions); + + /** + * Authenticates a request. + */ + authenticate( + request: OAuth2Server.Request, + response: OAuth2Server.Response, + options?: OAuth2Server.AuthenticateOptions, + callback?: OAuth2Server.Callback + ): Promise; + + /** + * Authorizes a token request. + */ + authorize( + request: OAuth2Server.Request, + response: OAuth2Server.Response, + options?: OAuth2Server.AuthorizeOptions, + callback?: OAuth2Server.Callback + ): Promise; + + /** + * Retrieves a new token for an authorized token request. + */ + token( + request: OAuth2Server.Request, + response: OAuth2Server.Response, + options?: OAuth2Server.TokenOptions, + callback?: OAuth2Server.Callback + ): Promise; +} + +declare namespace OAuth2Server { + /** + * Represents an incoming HTTP request. + */ + class Request { + body?: any; + headers?: { [key: string]: string; } | undefined; + method?: string | undefined; + query?: { [key: string]: string; } | undefined; + + /** + * Instantiates Request using the supplied options. + * + */ + constructor(options?: { [key: string]: any } | http.IncomingMessage); + + /** + * Returns the specified HTTP header field. The match is case-insensitive. + * + */ + get(field: string): any | undefined; + + /** + * Checks if the request’s Content-Type HTTP header matches any of the given MIME types. + * + */ + is(types: string[]): string | false; + } + + /** + * Represents an outgoing HTTP response. + */ + class Response { + body?: any; + headers?: { [key: string]: string; } | undefined; + status?: number | undefined; + + /** + * Instantiates Response using the supplied options. + * + */ + constructor(options?: { [key: string]: any; } | http.ServerResponse); + + /** + * Returns the specified HTTP header field. The match is case-insensitive. + * + */ + get(field: string): any | undefined; + + /** + * Sets the specified HTTP header field. The match is case-insensitive. + * + */ + set(field: string, value: string): void; + + /** + * Redirects to the specified URL using 302 Found. + * + */ + redirect(url: string): void; + } + + abstract class AbstractGrantType { + /** + * Instantiates AbstractGrantType using the supplied options. + * + */ + constructor(options: TokenOptions) + + /** + * Generate access token. Calls Model#generateAccessToken() if implemented. + * + */ + generateAccessToken(client: Client, user: User, scope: string | string[]): Promise; + + /** + * Generate refresh token. Calls Model#generateRefreshToken() if implemented. + * + */ + generateRefreshToken(client: Client, user: User, scope: string | string[]): Promise; + + /** + * Get access token expiration date. + * + */ + getAccessTokenExpiresAt(): Date; + + /** + * Get refresh token expiration date. + * + */ + getRefreshTokenExpiresAt(): Date; + + /** + * Get scope from the request body. + * + */ + getScope(request: Request): string; + + /** + * Validate requested scope. Calls Model#validateScope() if implemented. + * + */ + validateScope(user: User, client: Client, scope: string | string[]): Promise; + + /** + * Retrieve info from the request and client and return token + * + */ + abstract handle(request: Request, client: Client): Promise; + } + + interface ServerOptions extends AuthenticateOptions, AuthorizeOptions, TokenOptions { + /** + * Model object + */ + model: AuthorizationCodeModel | ClientCredentialsModel | RefreshTokenModel | PasswordModel | ExtensionModel; + } + + interface AuthenticateOptions { + /** + * The scope(s) to authenticate. + */ + scope?: string | string[] | undefined; + + /** + * Set the X-Accepted-OAuth-Scopes HTTP header on response objects. + */ + addAcceptedScopesHeader?: boolean | undefined; + + /** + * Set the X-OAuth-Scopes HTTP header on response objects. + */ + addAuthorizedScopesHeader?: boolean | undefined; + + /** + * Allow clients to pass bearer tokens in the query string of a request. + */ + allowBearerTokensInQueryString?: boolean | undefined; + } + + interface AuthorizeOptions { + /** + * The authenticate handler + */ + authenticateHandler?: {} | undefined; + + /** + * Allow clients to specify an empty state + */ + allowEmptyState?: boolean | undefined; + + /** + * Lifetime of generated authorization codes in seconds (default = 5 minutes). + */ + authorizationCodeLifetime?: number | undefined; + } + + interface TokenOptions { + /** + * Lifetime of generated access tokens in seconds (default = 1 hour) + */ + accessTokenLifetime?: number | undefined; + + /** + * Lifetime of generated refresh tokens in seconds (default = 2 weeks) + */ + refreshTokenLifetime?: number | undefined; + + /** + * Allow extended attributes to be set on the returned token + */ + allowExtendedTokenAttributes?: boolean | undefined; + + /** + * Require a client secret. Defaults to true for all grant types. + */ + requireClientAuthentication?: {} | undefined; + + /** + * Always revoke the used refresh token and issue a new one for the refresh_token grant. + */ + alwaysIssueNewRefreshToken?: boolean | undefined; + + /** + * Additional supported grant types. + */ + extendedGrantTypes?: { [key: string]: typeof AbstractGrantType } | undefined; + } + + /** + * Represents a generic callback structure for model callbacks + */ + type Callback = (err?: any, result?: T) => void; + + /** + * For returning falsey parameters in cases of failure + */ + type Falsey = '' | 0 | false | null | undefined; + + interface BaseModel { + /** + * Invoked to generate a new access token. + * + */ + generateAccessToken?(client: Client, user: User, scope: string | string[], callback?: Callback): Promise; + + /** + * Invoked to retrieve a client using a client id or a client id/client secret combination, depending on the grant type. + * + */ + getClient(clientId: string, clientSecret: string, callback?: Callback): Promise; + + /** + * Invoked to save an access token and optionally a refresh token, depending on the grant type. + * + */ + saveToken(token: Token, client: Client, user: User, callback?: Callback): Promise; + } + + interface RequestAuthenticationModel { + /** + * Invoked to retrieve an existing access token previously saved through Model#saveToken(). + * + */ + getAccessToken(accessToken: string, callback?: Callback): Promise; + + /** + * Invoked during request authentication to check if the provided access token was authorized the requested scopes. + * + */ + verifyScope(token: Token, scope: string | string[], callback?: Callback): Promise; + } + + interface AuthorizationCodeModel extends BaseModel, RequestAuthenticationModel { + /** + * Invoked to generate a new refresh token. + * + */ + generateRefreshToken?(client: Client, user: User, scope: string | string[], callback?: Callback): Promise; + + /** + * Invoked to generate a new authorization code. + * + */ + generateAuthorizationCode?(client: Client, user: User, scope: string | string[], callback?: Callback): Promise; + + /** + * Invoked to retrieve an existing authorization code previously saved through Model#saveAuthorizationCode(). + * + */ + getAuthorizationCode(authorizationCode: string, callback?: Callback): Promise; + + /** + * Invoked to save an authorization code. + * + */ + saveAuthorizationCode( + code: Pick, + client: Client, + user: User, + callback?: Callback): Promise; + + /** + * Invoked to revoke an authorization code. + * + */ + revokeAuthorizationCode(code: AuthorizationCode, callback?: Callback): Promise; + + /** + * Invoked to check if the requested scope is valid for a particular client/user combination. + * + */ + validateScope?(user: User, client: Client, scope: string | string[], callback?: Callback): Promise; + } + + interface PasswordModel extends BaseModel, RequestAuthenticationModel { + /** + * Invoked to generate a new refresh token. + * + */ + generateRefreshToken?(client: Client, user: User, scope: string | string[], callback?: Callback): Promise; + + /** + * Invoked to retrieve a user using a username/password combination. + * + */ + getUser(username: string, password: string, callback?: Callback): Promise; + + /** + * Invoked to check if the requested scope is valid for a particular client/user combination. + * + */ + validateScope?(user: User, client: Client, scope: string | string[], callback?: Callback): Promise; + } + + interface RefreshTokenModel extends BaseModel, RequestAuthenticationModel { + /** + * Invoked to generate a new refresh token. + * + */ + generateRefreshToken?(client: Client, user: User, scope: string | string[], callback?: Callback): Promise; + + /** + * Invoked to retrieve an existing refresh token previously saved through Model#saveToken(). + * + */ + getRefreshToken(refreshToken: string, callback?: Callback): Promise; + + /** + * Invoked to revoke a refresh token. + * + */ + revokeToken(token: RefreshToken | Token, callback?: Callback): Promise; + } + + interface ClientCredentialsModel extends BaseModel, RequestAuthenticationModel { + /** + * Invoked to retrieve the user associated with the specified client. + * + */ + getUserFromClient(client: Client, callback?: Callback): Promise; + + /** + * Invoked to check if the requested scope is valid for a particular client/user combination. + * + */ + validateScope?(user: User, client: Client, scope: string | string[], callback?: Callback): Promise; + } + + interface ExtensionModel extends BaseModel, RequestAuthenticationModel {} + + /** + * An interface representing the user. + * A user object is completely transparent to oauth2-server and is simply used as input to model functions. + */ + interface User { + [key: string]: any; + } + + /** + * An interface representing the client and associated data + */ + interface Client { + id: string; + redirectUris?: string | string[] | undefined; + grants: string | string[]; + accessTokenLifetime?: number | undefined; + refreshTokenLifetime?: number | undefined; + [key: string]: any; + } + + /** + * An interface representing the authorization code and associated data. + */ + interface AuthorizationCode { + authorizationCode: string; + expiresAt: Date; + redirectUri: string; + scope?: string | string[] | undefined; + client: Client; + user: User; + [key: string]: any; + } + + /** + * An interface representing the token(s) and associated data. + */ + interface Token { + accessToken: string; + accessTokenExpiresAt?: Date | undefined; + refreshToken?: string | undefined; + refreshTokenExpiresAt?: Date | undefined; + scope?: string | string[] | undefined; + client: Client; + user: User; + [key: string]: any; + } + + /** + * An interface representing the refresh token and associated data. + */ + interface RefreshToken { + refreshToken: string; + refreshTokenExpiresAt?: Date | undefined; + scope?: string | string[] | undefined; + client: Client; + user: User; + [key: string]: any; + } + + class OAuthError extends Error { + constructor(messageOrError: string | Error, properties?: object); + + /** + * The HTTP error code. + */ + code: number; + + /** + * The OAuth error code. + */ + name: string; + + /** + * A human-readable error message. + */ + message: string; + } + + class AccessDeniedError extends OAuthError {} + class InsufficientScopeError extends OAuthError {} + class InvalidArgumentError extends OAuthError {} + class InvalidClientError extends OAuthError {} + class InvalidGrantError extends OAuthError {} + class InvalidRequestError extends OAuthError {} + class InvalidScopeError extends OAuthError {} + class InvalidTokenError extends OAuthError {} + class ServerError extends OAuthError {} + class UnauthorizedClientError extends OAuthError {} + class UnauthorizedRequestError extends OAuthError {} + class UnsupportedGrantTypeError extends OAuthError {} + class UnsupportedResponseTypeError extends OAuthError {} +} + +export = OAuth2Server; diff --git a/package.json b/package.json index beaeb89..7cede2a 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "Daniel Reguero" ], "main": "index.js", + "types": "index.d.ts", "dependencies": { "basic-auth": "2.0.1", "bluebird": "3.7.2",