Skip to content

Commit b0c777d

Browse files
Danilo AlonsoDanilo Alonso
Danilo Alonso
authored and
Danilo Alonso
committed
feat: 🎸 add types
1 parent 4832baf commit b0c777d

File tree

3 files changed

+451
-1
lines changed

3 files changed

+451
-1
lines changed

‎lib/index.d.ts

+305
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
import { AuthCredentials, Plugin, Request } from '@hapi/hapi';
2+
3+
declare module '@hapi/hapi' {
4+
interface ServerAuth {
5+
strategy(name: string, scheme: 'bell', options: BellOptions): void;
6+
}
7+
}
8+
9+
export interface StringLikeMap {
10+
[key: string]: string | number;
11+
}
12+
export type Provider =
13+
| 'arcgisonline'
14+
| 'auth0'
15+
| 'azure'
16+
| 'bitbucket'
17+
| 'cognito'
18+
| 'digitalocean'
19+
| 'discord'
20+
| 'dropbox'
21+
| 'facebook'
22+
| 'fitbit'
23+
| 'foursquare'
24+
| 'github'
25+
| 'gitlab'
26+
| 'google'
27+
| 'googleplus'
28+
| 'instagram'
29+
| 'linkedin'
30+
| 'live'
31+
| 'medium'
32+
| 'meetup'
33+
| 'mixer'
34+
| 'nest'
35+
| 'okta'
36+
| 'phabricator'
37+
| 'pingfed'
38+
| 'pinterest'
39+
| 'reddit'
40+
| 'salesforce'
41+
| 'slack'
42+
| 'spotify'
43+
| 'stripe'
44+
| 'trakt'
45+
| 'tumblr'
46+
| 'twitch'
47+
| 'twitter'
48+
| 'vk'
49+
| 'wordpress'
50+
| 'yahoo';
51+
52+
export type RequestPassThrough = (request: Request) => PromiseLike<AuthCredentials> | AuthCredentials;
53+
54+
export interface OptionalOptions {
55+
/**
56+
* the name of the cookie used to manage the temporary state.
57+
* Defaults to 'bell-provider' where 'provider' is the provider name (or 'custom' for custom providers).
58+
* For example, the Twitter cookie name defaults to 'bell-twitter'.
59+
*/
60+
cookie?: string | undefined;
61+
/**
62+
* sets the cookie secure flag.
63+
* Defaults to true.
64+
*/
65+
isSecure?: boolean | undefined;
66+
/**
67+
* sets the cookie HTTP only flag.
68+
* Defaults to true.
69+
*/
70+
isHttpOnly?: boolean | undefined;
71+
/**
72+
* cookie time-to-live in milliseconds.
73+
* Defaults to null (session time-life - cookies are deleted when the browser is closed).
74+
*/
75+
ttl?: number | undefined;
76+
/**
77+
* the domain scope.
78+
* Defaults to null (no domain).
79+
*/
80+
domain?: string | undefined;
81+
/**
82+
* provider-specific query parameters for the authentication endpoint.
83+
* It may be passed either as an object to merge into the query string,
84+
* or a function which takes the client's request and returns an object.
85+
* Each provider supports its own set of parameters which customize the user's login experience.
86+
* For example:
87+
* * Facebook supports `display` ('page', 'popup', or 'touch'), `auth_type`, `auth_nonce`.
88+
* * Google supports `access_type`, `approval_prompt`, `prompt`, `login_hint`, `user_id`, `hd`.
89+
* * Twitter supports `force_login`, `screen_name`.
90+
* * Linkedin supports `fields`.
91+
*/
92+
providerParams?: StringLikeMap | ((request: Request) => StringLikeMap) | undefined;
93+
/**
94+
* allows passing query parameters from a bell protected endpoint to the auth request.
95+
* It will merge the query params you pass along with the providerParams and any other predefined ones.
96+
* Be aware that this will override predefined query parameters!
97+
* Default to false.
98+
*/
99+
allowRuntimeProviderParams?: StringLikeMap | boolean | undefined;
100+
/**
101+
* Each built-in vendor comes with the required scope for basic profile information.
102+
* Use scope to specify a different scope as required by your application.
103+
* It may be passed either as an object to merge into the query string,
104+
* or a function which takes the client's request and returns an object.
105+
* Consult the provider for their specific supported scopes.
106+
*/
107+
scope?: string[] | ((request: Request) => string[]) | undefined;
108+
/**
109+
* skips obtaining a user profile from the provider.
110+
* Useful if you need specific scopes,
111+
* but not the user profile.
112+
* Defaults to false.
113+
*/
114+
skipProfile?: boolean | undefined;
115+
/**
116+
* a configuration object used to customize the provider settings.
117+
* The built-in 'twitter' provider accepts the `extendedProfile` & `getMethod` options.
118+
* option which allows disabling the extra profile request when the provider
119+
* returns the user information in the callback (defaults to true).
120+
* The built-in 'github' and 'phabricator' providers accept the uri
121+
* option which allows pointing to a private enterprise installation (e.g. 'https://vpn.example.com').
122+
* See Providers documentation for more information.
123+
*/
124+
config?:
125+
| { extendedProfile?: boolean | undefined; getMethod?: string | undefined }
126+
| { uri?: string | undefined }
127+
| undefined;
128+
/**
129+
* an object of key-value pairs that specify additional
130+
* URL query parameters to send with the profile request to the provider.
131+
* The built-in facebook provider,
132+
* for example, could have fields specified to determine the fields returned from the user's graph,
133+
* which would then be available to you in the auth.credentials.profile.raw object.
134+
*/
135+
profileParams?: StringLikeMap | undefined;
136+
/**
137+
* allows passing additional OAuth state from initial request.
138+
* This must be a function returning a string,
139+
* which will be appended to the bell internal state parameter for OAuth code flow.
140+
*/
141+
runtimeStateCallback?(req: Request): string;
142+
143+
// THESE ARE IN THE *REQUIRED* section but are actually not...
144+
/**
145+
* A boolean indicating whether or not you want the redirect_uri to be forced to https.
146+
* Useful if your hapi application runs as http, but is accessed through https.
147+
*/
148+
forceHttps?: boolean | undefined;
149+
/**
150+
* Set the base redirect_uri manually if it cannot be inferred properly from server settings.
151+
* Useful to override port, protocol, and host if proxied or forwarded.
152+
*/
153+
location?: string | ((req: Request) => string) | undefined;
154+
}
155+
156+
export interface RequiredProviderOptions {
157+
/**
158+
* the cookie encryption password.
159+
* Used to encrypt the temporary state cookie used by the module in
160+
* between the authorization protocol steps.
161+
*/
162+
password: string;
163+
/**
164+
* the OAuth client identifier (consumer key).
165+
*/
166+
clientId: string;
167+
/**
168+
* the OAuth client secret (consumer secret)
169+
*/
170+
clientSecret: string;
171+
}
172+
173+
export interface KnownProviderOptions extends RequiredProviderOptions, OptionalOptions {
174+
provider: Provider;
175+
}
176+
177+
/**
178+
* @param uri the requested resource URI (bell will add the token or authentication header as needed).
179+
* @param params any URI query parameters (cannot include them in the URI due to signature requirements).
180+
*/
181+
export type AuthedRequest = (uri: string, params?: { [key: string]: string }) => Promise<object>;
182+
183+
export interface Credentials {
184+
provider: Provider | 'custom';
185+
token: string;
186+
query: StringLikeMap;
187+
/**
188+
* Varying data depending on provider.
189+
*/
190+
profile?: object | undefined;
191+
}
192+
193+
export interface Credentials1 extends Credentials {
194+
secret: string;
195+
}
196+
197+
export interface Credentials2 extends Credentials {
198+
refreshToken?: string | undefined;
199+
expiresIn?: number | undefined;
200+
}
201+
202+
export interface CustomProtocol {
203+
/**
204+
* The name of the protocol.
205+
* @default custom
206+
*/
207+
name?: string | undefined;
208+
/**
209+
* the authorization endpoint URI.
210+
*/
211+
auth: string;
212+
/**
213+
* the access token endpoint URI.
214+
*/
215+
token: string;
216+
/**
217+
* a headers object with additional headers required by the provider
218+
* (e.g. GitHub required the 'User-Agent' header which is set by default).
219+
*/
220+
headers?: {
221+
[key: string]: string;
222+
} | undefined;
223+
}
224+
225+
/**
226+
* a function used to obtain user profile information and normalize it.
227+
* @param credentials the credentials object.
228+
* Change the object directly within the function (profile information is typically stored under credentials.profile).
229+
* @param params the parsed information received from the provider (e.g. token, secret, and other custom fields).
230+
* @param get an OAuth helper function to make authenticated requests using the credentials received.
231+
*/
232+
export type ProfileGetter<C extends Credentials> = (
233+
this: CustomProviderOptions,
234+
credentials: C,
235+
params: { [key: string]: string },
236+
get: AuthedRequest,
237+
) => Promise<void>;
238+
239+
export interface CustomProtocol1 extends CustomProtocol {
240+
/**
241+
* the authorization protocol used.
242+
*/
243+
protocol: 'oauth';
244+
245+
/**
246+
* the OAuth signature method. Must be one of:
247+
* * 'HMAC-SHA1' - default
248+
* * 'RSA-SHA1' - in that case, the clientSecret is your RSA private key
249+
*/
250+
signatureMethod?: 'HMAC-SHA1' | 'RSA-SHA1' | undefined;
251+
/**
252+
* the temporary credentials (request token) endpoint).
253+
*/
254+
temporary?: string | undefined;
255+
256+
profile: ProfileGetter<Credentials1>;
257+
}
258+
259+
export type PkceSetting = 'plain' | 'S256';
260+
261+
export interface CustomProtocol2 extends CustomProtocol {
262+
/**
263+
* the authorization protocol used.
264+
*/
265+
protocol: 'oauth2';
266+
/**
267+
* an array of scope strings.
268+
*/
269+
scope?: string[] | ((query: StringLikeMap) => string[]) | undefined;
270+
/**
271+
* boolean that determines if OAuth client id and client secret will be sent
272+
* as parameters as opposed to an Authorization header.
273+
* Defaults to false.
274+
*/
275+
useParamsAuth?: boolean | undefined;
276+
277+
/**
278+
* If specified, uses proof key exchange.
279+
*/
280+
pkce?: PkceSetting | undefined;
281+
282+
/**
283+
* the scope separator character. Only required when a provider has a broken OAuth 2.0 implementation. Defaults to space (Facebook and GitHub default to comma).
284+
*/
285+
scopeSeparator?: string | undefined;
286+
287+
profile: ProfileGetter<Credentials2>;
288+
}
289+
290+
export interface CustomProviderOptions extends RequiredProviderOptions, OptionalOptions {
291+
provider: CustomProtocol1 | CustomProtocol2;
292+
}
293+
294+
export type BellOptions = CustomProviderOptions | KnownProviderOptions;
295+
296+
export const plugin: Plugin<BellOptions>;
297+
/**
298+
* Enables simulation mode.
299+
*/
300+
export function simulate(credentialsFunc: RequestPassThrough): void;
301+
/**
302+
* [See docs](https://github.com/hapijs/bell/blob/master/API.md#simulated-authentication)
303+
* Disables simulation mode
304+
*/
305+
export function simulate(state: false): void;

‎package.json

+3-1
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
"version": "13.0.1",
55
"repository": "git://github.com/hapijs/bell",
66
"main": "lib/index.js",
7+
"types": "lib/index.d.ts",
78
"engines": {
89
"node": ">=14.0.0"
910
},
@@ -62,7 +63,8 @@
6263
"@hapi/hapi": "^21.2.1",
6364
"@hapi/hawk": "^8.0.0",
6465
"@hapi/lab": "^25.0.1",
65-
"@hapi/teamwork": "^6.0.0"
66+
"@hapi/teamwork": "^6.0.0",
67+
"typescript": "^5.4.2"
6668
},
6769
"scripts": {
6870
"test": "lab -a @hapi/code -t 100 -L -m 3000",

0 commit comments

Comments
 (0)