@atproto/lex-password-session 0.0.4 → 0.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/README.md +187 -167
- package/dist/error.d.ts +47 -0
- package/dist/error.d.ts.map +1 -1
- package/dist/error.js +47 -0
- package/dist/error.js.map +1 -1
- package/dist/lexicons/com/atproto/server/createAccount.defs.d.ts +28 -28
- package/dist/lexicons/com/atproto/server/createSession.defs.d.ts +28 -28
- package/dist/lexicons/com/atproto/server/getSession.defs.d.ts +16 -16
- package/dist/lexicons/com/atproto/server/refreshSession.defs.d.ts +20 -20
- package/dist/password-session.d.ts +189 -14
- package/dist/password-session.d.ts.map +1 -1
- package/dist/password-session.js +168 -14
- package/dist/password-session.js.map +1 -1
- package/package.json +6 -6
- package/src/error.ts +47 -0
- package/src/password-session.ts +189 -14
package/dist/error.js
CHANGED
|
@@ -2,13 +2,60 @@
|
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.LexAuthFactorError = void 0;
|
|
4
4
|
const lex_client_1 = require("@atproto/lex-client");
|
|
5
|
+
/**
|
|
6
|
+
* Error thrown when two-factor authentication (2FA) is required.
|
|
7
|
+
*
|
|
8
|
+
* This error is thrown by {@link PasswordSession.login} when the server
|
|
9
|
+
* requires an additional authentication factor (e.g., email code). Catch this
|
|
10
|
+
* error to prompt the user for their 2FA code and retry the login with the
|
|
11
|
+
* `authFactorToken` parameter.
|
|
12
|
+
*
|
|
13
|
+
* @example Handling 2FA requirement
|
|
14
|
+
* ```ts
|
|
15
|
+
* import { PasswordSession, LexAuthFactorError } from '@atproto/lex-password-session'
|
|
16
|
+
*
|
|
17
|
+
* try {
|
|
18
|
+
* const session = await PasswordSession.login({
|
|
19
|
+
* service: 'https://bsky.social',
|
|
20
|
+
* identifier: 'alice.bsky.social',
|
|
21
|
+
* password: 'xxxx-xxxx-xxxx-xxxx',
|
|
22
|
+
* })
|
|
23
|
+
* } catch (err) {
|
|
24
|
+
* if (err instanceof LexAuthFactorError) {
|
|
25
|
+
* // Prompt user for 2FA code
|
|
26
|
+
* const token = await promptUser('Enter 2FA code from email:')
|
|
27
|
+
*
|
|
28
|
+
* // Retry with the 2FA token
|
|
29
|
+
* const session = await PasswordSession.login({
|
|
30
|
+
* service: 'https://bsky.social',
|
|
31
|
+
* identifier: 'alice.bsky.social',
|
|
32
|
+
* password: 'xxxx-xxxx-xxxx-xxxx',
|
|
33
|
+
* authFactorToken: token,
|
|
34
|
+
* })
|
|
35
|
+
* }
|
|
36
|
+
* }
|
|
37
|
+
* ```
|
|
38
|
+
*
|
|
39
|
+
* @extends LexError
|
|
40
|
+
*/
|
|
5
41
|
class LexAuthFactorError extends lex_client_1.LexError {
|
|
6
42
|
cause;
|
|
7
43
|
name = 'LexAuthFactorError';
|
|
44
|
+
/**
|
|
45
|
+
* Creates a new LexAuthFactorError.
|
|
46
|
+
*
|
|
47
|
+
* @param cause - The underlying XRPC failure response from the server
|
|
48
|
+
*/
|
|
8
49
|
constructor(cause) {
|
|
9
50
|
super(cause.error, cause.message ?? 'Auth factor token required', { cause });
|
|
10
51
|
this.cause = cause;
|
|
11
52
|
}
|
|
53
|
+
/**
|
|
54
|
+
* Converts this error to an HTTP Response.
|
|
55
|
+
*
|
|
56
|
+
* @returns A 500 Internal Server Error response (2FA errors should not be
|
|
57
|
+
* exposed to end users in server contexts)
|
|
58
|
+
*/
|
|
12
59
|
toResponse() {
|
|
13
60
|
return Response.json({ error: 'InternalServerError' }, { status: 500 });
|
|
14
61
|
}
|
package/dist/error.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":";;;AAAA,oDAA2D;AAE3D,MAAa,kBAAmB,SAAQ,qBAAQ;
|
|
1
|
+
{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":";;;AAAA,oDAA2D;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAa,kBAAmB,SAAQ,qBAAQ;IAQzB;IAPrB,IAAI,GAAG,oBAAoB,CAAA;IAE3B;;;;OAIG;IACH,YAAqB,KAAkB;QACrC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,IAAI,4BAA4B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QADzD,UAAK,GAAL,KAAK,CAAa;IAEvC,CAAC;IAED;;;;;OAKG;IACM,UAAU;QACjB,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IACzE,CAAC;CACF;AArBD,gDAqBC","sourcesContent":["import { LexError, XrpcFailure } from '@atproto/lex-client'\n\n/**\n * Error thrown when two-factor authentication (2FA) is required.\n *\n * This error is thrown by {@link PasswordSession.login} when the server\n * requires an additional authentication factor (e.g., email code). Catch this\n * error to prompt the user for their 2FA code and retry the login with the\n * `authFactorToken` parameter.\n *\n * @example Handling 2FA requirement\n * ```ts\n * import { PasswordSession, LexAuthFactorError } from '@atproto/lex-password-session'\n *\n * try {\n * const session = await PasswordSession.login({\n * service: 'https://bsky.social',\n * identifier: 'alice.bsky.social',\n * password: 'xxxx-xxxx-xxxx-xxxx',\n * })\n * } catch (err) {\n * if (err instanceof LexAuthFactorError) {\n * // Prompt user for 2FA code\n * const token = await promptUser('Enter 2FA code from email:')\n *\n * // Retry with the 2FA token\n * const session = await PasswordSession.login({\n * service: 'https://bsky.social',\n * identifier: 'alice.bsky.social',\n * password: 'xxxx-xxxx-xxxx-xxxx',\n * authFactorToken: token,\n * })\n * }\n * }\n * ```\n *\n * @extends LexError\n */\nexport class LexAuthFactorError extends LexError {\n name = 'LexAuthFactorError'\n\n /**\n * Creates a new LexAuthFactorError.\n *\n * @param cause - The underlying XRPC failure response from the server\n */\n constructor(readonly cause: XrpcFailure) {\n super(cause.error, cause.message ?? 'Auth factor token required', { cause })\n }\n\n /**\n * Converts this error to an HTTP Response.\n *\n * @returns A 500 Internal Server Error response (2FA errors should not be\n * exposed to end users in server contexts)\n */\n override toResponse(): Response {\n return Response.json({ error: 'InternalServerError' }, { status: 500 })\n }\n}\n"]}
|
|
@@ -3,29 +3,29 @@ declare const $nsid = "com.atproto.server.createAccount";
|
|
|
3
3
|
export { $nsid };
|
|
4
4
|
/** Create an account. Implemented by PDS. */
|
|
5
5
|
declare const main: l.Procedure<"com.atproto.server.createAccount", l.ParamsSchema<{}>, l.Payload<"application/json", l.ObjectSchema<{
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
email: l.OptionalSchema<l.StringSchema<{}>>;
|
|
7
|
+
handle: l.StringSchema<{
|
|
8
8
|
readonly format: "handle";
|
|
9
9
|
}>;
|
|
10
|
-
|
|
10
|
+
did: l.OptionalSchema<l.StringSchema<{
|
|
11
11
|
readonly format: "did";
|
|
12
12
|
}>>;
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
13
|
+
inviteCode: l.OptionalSchema<l.StringSchema<{}>>;
|
|
14
|
+
verificationCode: l.OptionalSchema<l.StringSchema<{}>>;
|
|
15
|
+
verificationPhone: l.OptionalSchema<l.StringSchema<{}>>;
|
|
16
|
+
password: l.OptionalSchema<l.StringSchema<{}>>;
|
|
17
|
+
recoveryKey: l.OptionalSchema<l.StringSchema<{}>>;
|
|
18
|
+
plcOp: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
19
19
|
}>>, l.Payload<"application/json", l.ObjectSchema<{
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
accessJwt: l.StringSchema<{}>;
|
|
21
|
+
refreshJwt: l.StringSchema<{}>;
|
|
22
|
+
handle: l.StringSchema<{
|
|
23
23
|
readonly format: "handle";
|
|
24
24
|
}>;
|
|
25
|
-
|
|
25
|
+
did: l.StringSchema<{
|
|
26
26
|
readonly format: "did";
|
|
27
27
|
}>;
|
|
28
|
-
|
|
28
|
+
didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
29
29
|
}>>, readonly ["InvalidHandle", "InvalidPassword", "InvalidInviteCode", "HandleNotAvailable", "UnsupportedDomain", "UnresolvableDid", "IncompatibleDidDoc"]>;
|
|
30
30
|
export { main };
|
|
31
31
|
export type Params = l.InferMethodParams<typeof main>;
|
|
@@ -34,28 +34,28 @@ export type InputBody = l.InferMethodInputBody<typeof main>;
|
|
|
34
34
|
export type Output = l.InferMethodOutput<typeof main>;
|
|
35
35
|
export type OutputBody = l.InferMethodOutputBody<typeof main>;
|
|
36
36
|
export declare const $lxm: "com.atproto.server.createAccount", $params: l.ParamsSchema<{}>, $input: l.Payload<"application/json", l.ObjectSchema<{
|
|
37
|
-
|
|
38
|
-
|
|
37
|
+
email: l.OptionalSchema<l.StringSchema<{}>>;
|
|
38
|
+
handle: l.StringSchema<{
|
|
39
39
|
readonly format: "handle";
|
|
40
40
|
}>;
|
|
41
|
-
|
|
41
|
+
did: l.OptionalSchema<l.StringSchema<{
|
|
42
42
|
readonly format: "did";
|
|
43
43
|
}>>;
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
44
|
+
inviteCode: l.OptionalSchema<l.StringSchema<{}>>;
|
|
45
|
+
verificationCode: l.OptionalSchema<l.StringSchema<{}>>;
|
|
46
|
+
verificationPhone: l.OptionalSchema<l.StringSchema<{}>>;
|
|
47
|
+
password: l.OptionalSchema<l.StringSchema<{}>>;
|
|
48
|
+
recoveryKey: l.OptionalSchema<l.StringSchema<{}>>;
|
|
49
|
+
plcOp: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
50
50
|
}>>, $output: l.Payload<"application/json", l.ObjectSchema<{
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
51
|
+
accessJwt: l.StringSchema<{}>;
|
|
52
|
+
refreshJwt: l.StringSchema<{}>;
|
|
53
|
+
handle: l.StringSchema<{
|
|
54
54
|
readonly format: "handle";
|
|
55
55
|
}>;
|
|
56
|
-
|
|
56
|
+
did: l.StringSchema<{
|
|
57
57
|
readonly format: "did";
|
|
58
58
|
}>;
|
|
59
|
-
|
|
59
|
+
didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
60
60
|
}>>;
|
|
61
61
|
//# sourceMappingURL=createAccount.defs.d.ts.map
|
|
@@ -3,25 +3,25 @@ declare const $nsid = "com.atproto.server.createSession";
|
|
|
3
3
|
export { $nsid };
|
|
4
4
|
/** Create an authentication session. */
|
|
5
5
|
declare const main: l.Procedure<"com.atproto.server.createSession", l.ParamsSchema<{}>, l.Payload<"application/json", l.ObjectSchema<{
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
6
|
+
identifier: l.StringSchema<{}>;
|
|
7
|
+
password: l.StringSchema<{}>;
|
|
8
|
+
authFactorToken: l.OptionalSchema<l.StringSchema<{}>>;
|
|
9
|
+
allowTakendown: l.OptionalSchema<l.BooleanSchema>;
|
|
10
10
|
}>>, l.Payload<"application/json", l.ObjectSchema<{
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
11
|
+
accessJwt: l.StringSchema<{}>;
|
|
12
|
+
refreshJwt: l.StringSchema<{}>;
|
|
13
|
+
handle: l.StringSchema<{
|
|
14
14
|
readonly format: "handle";
|
|
15
15
|
}>;
|
|
16
|
-
|
|
16
|
+
did: l.StringSchema<{
|
|
17
17
|
readonly format: "did";
|
|
18
18
|
}>;
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
19
|
+
didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
20
|
+
email: l.OptionalSchema<l.StringSchema<{}>>;
|
|
21
|
+
emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
|
|
22
|
+
emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
|
|
23
|
+
active: l.OptionalSchema<l.BooleanSchema>;
|
|
24
|
+
status: l.OptionalSchema<l.StringSchema<{}>>;
|
|
25
25
|
}>>, readonly ["AccountTakedown", "AuthFactorTokenRequired"]>;
|
|
26
26
|
export { main };
|
|
27
27
|
export type Params = l.InferMethodParams<typeof main>;
|
|
@@ -30,24 +30,24 @@ export type InputBody = l.InferMethodInputBody<typeof main>;
|
|
|
30
30
|
export type Output = l.InferMethodOutput<typeof main>;
|
|
31
31
|
export type OutputBody = l.InferMethodOutputBody<typeof main>;
|
|
32
32
|
export declare const $lxm: "com.atproto.server.createSession", $params: l.ParamsSchema<{}>, $input: l.Payload<"application/json", l.ObjectSchema<{
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
33
|
+
identifier: l.StringSchema<{}>;
|
|
34
|
+
password: l.StringSchema<{}>;
|
|
35
|
+
authFactorToken: l.OptionalSchema<l.StringSchema<{}>>;
|
|
36
|
+
allowTakendown: l.OptionalSchema<l.BooleanSchema>;
|
|
37
37
|
}>>, $output: l.Payload<"application/json", l.ObjectSchema<{
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
38
|
+
accessJwt: l.StringSchema<{}>;
|
|
39
|
+
refreshJwt: l.StringSchema<{}>;
|
|
40
|
+
handle: l.StringSchema<{
|
|
41
41
|
readonly format: "handle";
|
|
42
42
|
}>;
|
|
43
|
-
|
|
43
|
+
did: l.StringSchema<{
|
|
44
44
|
readonly format: "did";
|
|
45
45
|
}>;
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
46
|
+
didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
47
|
+
email: l.OptionalSchema<l.StringSchema<{}>>;
|
|
48
|
+
emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
|
|
49
|
+
emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
|
|
50
|
+
active: l.OptionalSchema<l.BooleanSchema>;
|
|
51
|
+
status: l.OptionalSchema<l.StringSchema<{}>>;
|
|
52
52
|
}>>;
|
|
53
53
|
//# sourceMappingURL=createSession.defs.d.ts.map
|
|
@@ -3,35 +3,35 @@ declare const $nsid = "com.atproto.server.getSession";
|
|
|
3
3
|
export { $nsid };
|
|
4
4
|
/** Get information about the current auth session. Requires auth. */
|
|
5
5
|
declare const main: l.Query<"com.atproto.server.getSession", l.ParamsSchema<{}>, l.Payload<"application/json", l.ObjectSchema<{
|
|
6
|
-
|
|
6
|
+
handle: l.StringSchema<{
|
|
7
7
|
readonly format: "handle";
|
|
8
8
|
}>;
|
|
9
|
-
|
|
9
|
+
did: l.StringSchema<{
|
|
10
10
|
readonly format: "did";
|
|
11
11
|
}>;
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
12
|
+
didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
13
|
+
email: l.OptionalSchema<l.StringSchema<{}>>;
|
|
14
|
+
emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
|
|
15
|
+
emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
|
|
16
|
+
active: l.OptionalSchema<l.BooleanSchema>;
|
|
17
|
+
status: l.OptionalSchema<l.StringSchema<{}>>;
|
|
18
18
|
}>>, undefined>;
|
|
19
19
|
export { main };
|
|
20
20
|
export type Params = l.InferMethodParams<typeof main>;
|
|
21
21
|
export type Output = l.InferMethodOutput<typeof main>;
|
|
22
22
|
export type OutputBody = l.InferMethodOutputBody<typeof main>;
|
|
23
23
|
export declare const $lxm: "com.atproto.server.getSession", $params: l.ParamsSchema<{}>, $output: l.Payload<"application/json", l.ObjectSchema<{
|
|
24
|
-
|
|
24
|
+
handle: l.StringSchema<{
|
|
25
25
|
readonly format: "handle";
|
|
26
26
|
}>;
|
|
27
|
-
|
|
27
|
+
did: l.StringSchema<{
|
|
28
28
|
readonly format: "did";
|
|
29
29
|
}>;
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
30
|
+
didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
31
|
+
email: l.OptionalSchema<l.StringSchema<{}>>;
|
|
32
|
+
emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
|
|
33
|
+
emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
|
|
34
|
+
active: l.OptionalSchema<l.BooleanSchema>;
|
|
35
|
+
status: l.OptionalSchema<l.StringSchema<{}>>;
|
|
36
36
|
}>>;
|
|
37
37
|
//# sourceMappingURL=getSession.defs.d.ts.map
|
|
@@ -3,20 +3,20 @@ declare const $nsid = "com.atproto.server.refreshSession";
|
|
|
3
3
|
export { $nsid };
|
|
4
4
|
/** Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt'). */
|
|
5
5
|
declare const main: l.Procedure<"com.atproto.server.refreshSession", l.ParamsSchema<{}>, l.Payload<undefined, undefined>, l.Payload<"application/json", l.ObjectSchema<{
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
accessJwt: l.StringSchema<{}>;
|
|
7
|
+
refreshJwt: l.StringSchema<{}>;
|
|
8
|
+
handle: l.StringSchema<{
|
|
9
9
|
readonly format: "handle";
|
|
10
10
|
}>;
|
|
11
|
-
|
|
11
|
+
did: l.StringSchema<{
|
|
12
12
|
readonly format: "did";
|
|
13
13
|
}>;
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
14
|
+
didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
15
|
+
email: l.OptionalSchema<l.StringSchema<{}>>;
|
|
16
|
+
emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
|
|
17
|
+
emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
|
|
18
|
+
active: l.OptionalSchema<l.BooleanSchema>;
|
|
19
|
+
status: l.OptionalSchema<l.StringSchema<{}>>;
|
|
20
20
|
}>>, readonly ["AccountTakedown", "InvalidToken", "ExpiredToken"]>;
|
|
21
21
|
export { main };
|
|
22
22
|
export type Params = l.InferMethodParams<typeof main>;
|
|
@@ -25,19 +25,19 @@ export type InputBody = l.InferMethodInputBody<typeof main>;
|
|
|
25
25
|
export type Output = l.InferMethodOutput<typeof main>;
|
|
26
26
|
export type OutputBody = l.InferMethodOutputBody<typeof main>;
|
|
27
27
|
export declare const $lxm: "com.atproto.server.refreshSession", $params: l.ParamsSchema<{}>, $input: l.Payload<undefined, undefined>, $output: l.Payload<"application/json", l.ObjectSchema<{
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
28
|
+
accessJwt: l.StringSchema<{}>;
|
|
29
|
+
refreshJwt: l.StringSchema<{}>;
|
|
30
|
+
handle: l.StringSchema<{
|
|
31
31
|
readonly format: "handle";
|
|
32
32
|
}>;
|
|
33
|
-
|
|
33
|
+
did: l.StringSchema<{
|
|
34
34
|
readonly format: "did";
|
|
35
35
|
}>;
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
36
|
+
didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
|
|
37
|
+
email: l.OptionalSchema<l.StringSchema<{}>>;
|
|
38
|
+
emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
|
|
39
|
+
emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
|
|
40
|
+
active: l.OptionalSchema<l.BooleanSchema>;
|
|
41
|
+
status: l.OptionalSchema<l.StringSchema<{}>>;
|
|
42
42
|
}>>;
|
|
43
43
|
//# sourceMappingURL=refreshSession.defs.d.ts.map
|
|
@@ -1,7 +1,28 @@
|
|
|
1
1
|
import { Agent, XrpcFailure } from '@atproto/lex-client';
|
|
2
2
|
import { com } from './lexicons/index.js';
|
|
3
|
+
/**
|
|
4
|
+
* Represents a failure response when refreshing a session.
|
|
5
|
+
*
|
|
6
|
+
* This type captures the possible error responses from
|
|
7
|
+
* `com.atproto.server.refreshSession`, including both expected errors
|
|
8
|
+
* (e.g., invalid/expired refresh token) and unexpected errors (e.g., network issues).
|
|
9
|
+
*/
|
|
3
10
|
export type RefreshFailure = XrpcFailure<typeof com.atproto.server.refreshSession.main>;
|
|
11
|
+
/**
|
|
12
|
+
* Represents a failure response when deleting a session.
|
|
13
|
+
*
|
|
14
|
+
* This type captures the possible error responses from
|
|
15
|
+
* `com.atproto.server.deleteSession`, including both expected errors
|
|
16
|
+
* and unexpected errors (e.g., network issues, server unavailability).
|
|
17
|
+
*/
|
|
4
18
|
export type DeleteFailure = XrpcFailure<typeof com.atproto.server.deleteSession.main>;
|
|
19
|
+
/**
|
|
20
|
+
* Persisted session data containing authentication credentials and service information.
|
|
21
|
+
*
|
|
22
|
+
* This type extends the response from `com.atproto.server.createSession` with the
|
|
23
|
+
* service URL used for authentication. Store this data securely to resume sessions
|
|
24
|
+
* later without re-authenticating.
|
|
25
|
+
*/
|
|
5
26
|
export type SessionData = com.atproto.server.createSession.OutputBody & {
|
|
6
27
|
service: string;
|
|
7
28
|
};
|
|
@@ -55,45 +76,199 @@ export type PasswordSessionOptions = {
|
|
|
55
76
|
*/
|
|
56
77
|
onDeleteFailure?: (this: PasswordSession, data: SessionData, err: DeleteFailure) => void | Promise<void>;
|
|
57
78
|
};
|
|
79
|
+
/**
|
|
80
|
+
* Password-based authentication session for AT Protocol services.
|
|
81
|
+
*
|
|
82
|
+
* This class provides session management for CLI tools, scripts, and bots that
|
|
83
|
+
* need to authenticate with AT Protocol services using password credentials.
|
|
84
|
+
* It implements the {@link Agent} interface, allowing it to be used directly
|
|
85
|
+
* with AT Protocol clients.
|
|
86
|
+
*
|
|
87
|
+
* **Security Warning:** It is strongly recommended to use app passwords instead
|
|
88
|
+
* of main account credentials. App passwords provide limited access and can be
|
|
89
|
+
* revoked independently without compromising your main account. For browser-based
|
|
90
|
+
* applications, use OAuth-based authentication instead.
|
|
91
|
+
*
|
|
92
|
+
* @example Basic usage with app password
|
|
93
|
+
* ```ts
|
|
94
|
+
* const session = await PasswordSession.login({
|
|
95
|
+
* service: 'https://bsky.social',
|
|
96
|
+
* identifier: 'alice.bsky.social',
|
|
97
|
+
* password: 'xxxx-xxxx-xxxx-xxxx', // App password
|
|
98
|
+
* onUpdated: (data) => saveToStorage(data),
|
|
99
|
+
* onDeleted: (data) => clearStorage(data.did),
|
|
100
|
+
* })
|
|
101
|
+
*
|
|
102
|
+
* const client = new Client(session)
|
|
103
|
+
* // Use client to make authenticated requests
|
|
104
|
+
* ```
|
|
105
|
+
*
|
|
106
|
+
* @example Resuming a persisted session
|
|
107
|
+
* ```ts
|
|
108
|
+
* const savedData = JSON.parse(fs.readFileSync('session.json', 'utf8'))
|
|
109
|
+
* const session = await PasswordSession.resume(savedData, {
|
|
110
|
+
* onUpdated: (data) => saveToStorage(data),
|
|
111
|
+
* onDeleted: (data) => clearStorage(data.did),
|
|
112
|
+
* })
|
|
113
|
+
* ```
|
|
114
|
+
*
|
|
115
|
+
* @implements {Agent}
|
|
116
|
+
*/
|
|
58
117
|
export declare class PasswordSession implements Agent {
|
|
59
118
|
#private;
|
|
60
119
|
protected readonly options: PasswordSessionOptions;
|
|
61
120
|
constructor(sessionData: SessionData, options?: PasswordSessionOptions);
|
|
121
|
+
/**
|
|
122
|
+
* The DID (Decentralized Identifier) of the authenticated account.
|
|
123
|
+
*
|
|
124
|
+
* @throws {Error} If the session has been destroyed (logged out).
|
|
125
|
+
*/
|
|
62
126
|
get did(): `did:${string}:${string}`;
|
|
127
|
+
/**
|
|
128
|
+
* The handle (username) of the authenticated account.
|
|
129
|
+
*
|
|
130
|
+
* @throws {Error} If the session has been destroyed (logged out).
|
|
131
|
+
*/
|
|
63
132
|
get handle(): `${string}.${string}`;
|
|
133
|
+
/**
|
|
134
|
+
* The current session data containing authentication credentials.
|
|
135
|
+
*
|
|
136
|
+
* @throws {Error} If the session has been destroyed (logged out).
|
|
137
|
+
*/
|
|
64
138
|
get session(): SessionData;
|
|
139
|
+
/**
|
|
140
|
+
* Whether this session has been destroyed (logged out).
|
|
141
|
+
*
|
|
142
|
+
* Once destroyed, this session instance can no longer be used for
|
|
143
|
+
* authenticated requests. Create a new session via {@link PasswordSession.login}
|
|
144
|
+
* or {@link PasswordSession.resume}.
|
|
145
|
+
*/
|
|
65
146
|
get destroyed(): boolean;
|
|
147
|
+
/**
|
|
148
|
+
* Handles authenticated fetch requests to the user's PDS.
|
|
149
|
+
*
|
|
150
|
+
* This method implements the {@link Agent} interface and is called by
|
|
151
|
+
* AT Protocol clients to make authenticated requests. It automatically:
|
|
152
|
+
* - Adds the access token to request headers
|
|
153
|
+
* - Detects expired tokens and triggers refresh
|
|
154
|
+
* - Retries requests after successful token refresh
|
|
155
|
+
*
|
|
156
|
+
* @param path - The request path (will be resolved against the PDS URL)
|
|
157
|
+
* @param init - Standard fetch RequestInit options (headers, body, etc.)
|
|
158
|
+
* @returns The fetch Response from the PDS
|
|
159
|
+
* @throws {TypeError} If an 'authorization' header is already set in init
|
|
160
|
+
*/
|
|
66
161
|
fetchHandler(path: string, init: RequestInit): Promise<Response>;
|
|
162
|
+
/**
|
|
163
|
+
* Refreshes the session by obtaining new access and refresh tokens.
|
|
164
|
+
*
|
|
165
|
+
* This method is automatically called by {@link fetchHandler} when the access
|
|
166
|
+
* token expires. You can also call it manually to proactively refresh tokens.
|
|
167
|
+
*
|
|
168
|
+
* On success, the {@link PasswordSessionOptions.onUpdated} callback is invoked
|
|
169
|
+
* with the new session data. On expected failures (invalid session), the
|
|
170
|
+
* {@link PasswordSessionOptions.onDeleted} callback is invoked. On unexpected
|
|
171
|
+
* failures (network issues), the {@link PasswordSessionOptions.onUpdateFailure}
|
|
172
|
+
* callback is invoked and the existing session data is preserved.
|
|
173
|
+
*
|
|
174
|
+
* @returns The refreshed session data
|
|
175
|
+
* @throws {RefreshFailure} If the session is no longer valid (triggers onDeleted)
|
|
176
|
+
*/
|
|
67
177
|
refresh(): Promise<SessionData>;
|
|
178
|
+
/**
|
|
179
|
+
* Logs out by deleting the session on the server.
|
|
180
|
+
*
|
|
181
|
+
* This method invalidates both the access and refresh tokens on the server,
|
|
182
|
+
* preventing any further use of this session. After successful logout, the
|
|
183
|
+
* session is marked as destroyed and the {@link PasswordSessionOptions.onDeleted}
|
|
184
|
+
* callback is invoked.
|
|
185
|
+
*
|
|
186
|
+
* If the logout request fails due to network issues or server unavailability,
|
|
187
|
+
* the {@link PasswordSessionOptions.onDeleteFailure} callback is invoked and
|
|
188
|
+
* the session remains active locally. In this case, you should retry the
|
|
189
|
+
* logout later to ensure the session is properly invalidated on the server.
|
|
190
|
+
*
|
|
191
|
+
* @throws {DeleteFailure} If the logout request fails due to unexpected errors
|
|
192
|
+
*/
|
|
68
193
|
logout(): Promise<void>;
|
|
194
|
+
/**
|
|
195
|
+
* Creates a new account and returns an authenticated session.
|
|
196
|
+
*
|
|
197
|
+
* This static method registers a new account on the specified service and
|
|
198
|
+
* automatically creates an authenticated session for it.
|
|
199
|
+
*
|
|
200
|
+
* @param body - Account creation parameters (handle, email, password, etc.)
|
|
201
|
+
* @param options - Session options including the service URL
|
|
202
|
+
* @returns A new PasswordSession for the created account
|
|
203
|
+
* @throws If account creation fails (e.g., handle taken, invalid invite code)
|
|
204
|
+
*
|
|
205
|
+
* @example
|
|
206
|
+
* ```ts
|
|
207
|
+
* const session = await PasswordSession.createAccount(
|
|
208
|
+
* {
|
|
209
|
+
* handle: 'alice.bsky.social',
|
|
210
|
+
* email: 'alice@example.com',
|
|
211
|
+
* password: 'secure-password',
|
|
212
|
+
* },
|
|
213
|
+
* {
|
|
214
|
+
* service: 'https://bsky.social',
|
|
215
|
+
* onUpdated: (data) => saveToStorage(data),
|
|
216
|
+
* }
|
|
217
|
+
* )
|
|
218
|
+
* ```
|
|
219
|
+
*/
|
|
69
220
|
static createAccount(body: com.atproto.server.createAccount.InputBody, { service, headers, ...options }: PasswordSessionOptions & {
|
|
70
221
|
headers?: HeadersInit;
|
|
71
222
|
service: string | URL;
|
|
72
223
|
}): Promise<PasswordSession>;
|
|
73
224
|
/**
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
* use-cases.
|
|
225
|
+
* Creates a new authenticated session using password credentials.
|
|
226
|
+
*
|
|
227
|
+
* This static method authenticates with the specified service and returns
|
|
228
|
+
* a new PasswordSession instance that can be used for authenticated requests.
|
|
79
229
|
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
230
|
+
* **Security Warning:** It is strongly recommended to use app passwords instead
|
|
231
|
+
* of main account credentials. App passwords can be created in your account
|
|
232
|
+
* settings and provide limited access that can be revoked independently. For
|
|
233
|
+
* browser-based applications, use OAuth-based authentication instead.
|
|
83
234
|
*
|
|
235
|
+
* @param options - Login options including service URL, identifier, and password
|
|
236
|
+
* @param options.service - The AT Protocol service URL (e.g., 'https://bsky.social')
|
|
237
|
+
* @param options.identifier - The user's handle or DID
|
|
238
|
+
* @param options.password - The user's password or app password
|
|
239
|
+
* @param options.allowTakendown - If true, allow login to takendown accounts
|
|
240
|
+
* @param options.authFactorToken - 2FA token if required by the server
|
|
241
|
+
* @returns A new authenticated PasswordSession
|
|
242
|
+
* @throws {LexAuthFactorError} If the server requires a 2FA token
|
|
243
|
+
* @throws If authentication fails (invalid credentials, etc.)
|
|
84
244
|
*
|
|
85
|
-
* @example
|
|
245
|
+
* @example Basic login with app password
|
|
246
|
+
* ```ts
|
|
247
|
+
* const session = await PasswordSession.login({
|
|
248
|
+
* service: 'https://bsky.social',
|
|
249
|
+
* identifier: 'alice.bsky.social',
|
|
250
|
+
* password: 'xxxx-xxxx-xxxx-xxxx', // App password
|
|
251
|
+
* onUpdated: (data) => saveToStorage(data),
|
|
252
|
+
* })
|
|
253
|
+
* ```
|
|
86
254
|
*
|
|
255
|
+
* @example Handling 2FA requirement
|
|
87
256
|
* ```ts
|
|
88
257
|
* try {
|
|
89
258
|
* const session = await PasswordSession.login({
|
|
90
|
-
* service: 'https://
|
|
91
|
-
* identifier: 'alice',
|
|
92
|
-
* password: '
|
|
259
|
+
* service: 'https://bsky.social',
|
|
260
|
+
* identifier: 'alice.bsky.social',
|
|
261
|
+
* password: 'xxxx-xxxx-xxxx-xxxx',
|
|
93
262
|
* })
|
|
94
263
|
* } catch (err) {
|
|
95
|
-
* if (err instanceof
|
|
96
|
-
*
|
|
264
|
+
* if (err instanceof LexAuthFactorError) {
|
|
265
|
+
* const token = await promptUser('Enter 2FA code:')
|
|
266
|
+
* const session = await PasswordSession.login({
|
|
267
|
+
* service: 'https://bsky.social',
|
|
268
|
+
* identifier: 'alice.bsky.social',
|
|
269
|
+
* password: 'xxxx-xxxx-xxxx-xxxx',
|
|
270
|
+
* authFactorToken: token,
|
|
271
|
+
* })
|
|
97
272
|
* }
|
|
98
273
|
* }
|
|
99
274
|
* ```
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"password-session.d.ts","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,WAAW,EAIZ,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAA;AAGzC,MAAM,MAAM,cAAc,GAAG,WAAW,CACtC,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAC9C,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,CACrC,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAC7C,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,GAAG;IACtE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAE/B;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9E;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,CAChB,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,cAAc,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9E;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,CAChB,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,aAAa,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B,CAAA;AAED,qBAAa,eAAgB,YAAW,KAAK;;IAYzC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB;gBADlD,WAAW,EAAE,WAAW,EACL,OAAO,GAAE,sBAA2B;IAWzD,IAAI,GAAG,8BAEN;IAED,IAAI,MAAM,0BAET;IAED,IAAI,OAAO,gBAGV;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;
|
|
1
|
+
{"version":3,"file":"password-session.d.ts","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"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"}
|