@kayjs/auth 1.104.3 → 1.105.0

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.
Files changed (206) hide show
  1. package/llms/admin-and-organizations.md +8 -8
  2. package/llms/admin-pages.md +2 -2
  3. package/llms/grouped-methods.md +33 -17
  4. package/llms/hardening-and-testing.md +9 -9
  5. package/llms/oauth-passkeys-two-factor.md +13 -13
  6. package/llms/oauth-providers.md +1 -1
  7. package/llms/oauth-server-and-tokens.md +7 -7
  8. package/llms/passwords-and-mails.md +12 -12
  9. package/llms/sessions-and-guards.md +9 -1
  10. package/llms/setup.md +6 -6
  11. package/llms/signed-in-components.md +20 -11
  12. package/llms.txt +1 -1
  13. package/package.json +9 -5
  14. package/src/account.ts +6 -15
  15. package/src/admin.ts +9 -25
  16. package/src/auth.ts +9 -6
  17. package/src/authorize/clients.ts +1 -1
  18. package/src/authorize/grants.ts +2 -4
  19. package/src/authorize/request.ts +2 -4
  20. package/src/bearer.ts +5 -11
  21. package/src/captcha.ts +5 -3
  22. package/src/components/sign-in-link.kay +19 -0
  23. package/src/components/sign-out-button.kay +17 -0
  24. package/src/components/signed-in.kay +7 -2
  25. package/src/components/user-menu.kay +11 -8
  26. package/src/context.ts +1 -1
  27. package/src/deletion.ts +2 -4
  28. package/src/email.ts +16 -28
  29. package/src/erase.ts +5 -4
  30. package/src/export.ts +2 -4
  31. package/src/failure.ts +37 -9
  32. package/src/guard.ts +8 -1
  33. package/src/guards.ts +12 -5
  34. package/src/index.ts +14 -16
  35. package/src/limits.ts +97 -5
  36. package/src/mail.ts +5 -3
  37. package/src/memoryStore.ts +6 -6
  38. package/src/messages/fr.ts +1 -0
  39. package/src/methods/account.ts +30 -14
  40. package/src/methods/admin.ts +31 -14
  41. package/src/methods/captcha.ts +18 -0
  42. package/src/methods/email.ts +16 -7
  43. package/src/methods/magicLink.ts +5 -5
  44. package/src/methods/oauth.ts +16 -7
  45. package/src/methods/oauthServer.ts +32 -6
  46. package/src/methods/organizations.ts +51 -20
  47. package/src/methods/passkeys.ts +13 -7
  48. package/src/methods/password.ts +10 -10
  49. package/src/methods/proof.ts +22 -0
  50. package/src/methods/sessions.ts +3 -2
  51. package/src/methods/tokens.ts +17 -5
  52. package/src/methods/twoFactor.ts +10 -10
  53. package/src/oauth/flow.ts +2 -4
  54. package/src/oauthTest.ts +8 -4
  55. package/src/organizations.ts +12 -30
  56. package/src/organizationsCore.ts +1 -1
  57. package/src/own.ts +17 -15
  58. package/src/pages/components/frame.kay +3 -3
  59. package/src/pages/components/passkey-add.kay +2 -2
  60. package/src/pages/components/passkey-sign-in.kay +2 -2
  61. package/src/pages/components/passkey-two-factor.kay +2 -2
  62. package/src/pages/components/provider-buttons.kay +1 -1
  63. package/src/pages/forms.ts +6 -6
  64. package/src/pages/index.ts +9 -8
  65. package/src/pages/routes/account/clients.kay +2 -2
  66. package/src/pages/routes/account/connections.kay +4 -4
  67. package/src/pages/routes/account/data.kay +7 -7
  68. package/src/pages/routes/account/index.kay +15 -15
  69. package/src/pages/routes/account/organizations/[org].kay +15 -15
  70. package/src/pages/routes/account/organizations/index.kay +5 -5
  71. package/src/pages/routes/account/security.kay +15 -15
  72. package/src/pages/routes/account/tokens.kay +4 -4
  73. package/src/pages/routes/admin/_layout.kay +1 -1
  74. package/src/pages/routes/admin/audit.kay +1 -1
  75. package/src/pages/routes/admin/users/[id].kay +11 -11
  76. package/src/pages/routes/confirm-email.kay +3 -3
  77. package/src/pages/routes/invitation.kay +8 -8
  78. package/src/pages/routes/magic-link.kay +3 -3
  79. package/src/pages/routes/oauth/authorize.kay +2 -2
  80. package/src/pages/routes/register.kay +4 -4
  81. package/src/pages/routes/reset-password.kay +6 -6
  82. package/src/pages/routes/sign-in.kay +10 -10
  83. package/src/pages/routes/two-factor.kay +4 -4
  84. package/src/pages/routes/verify-email.kay +8 -8
  85. package/src/passkeys.ts +10 -21
  86. package/src/password.ts +8 -11
  87. package/src/pg.ts +3 -3
  88. package/src/profile.ts +1 -3
  89. package/src/proof.ts +3 -5
  90. package/src/request.ts +77 -46
  91. package/src/requiredTwoFactor.ts +2 -2
  92. package/src/routes.ts +2 -2
  93. package/src/sessions.ts +3 -7
  94. package/src/setup.ts +6 -4
  95. package/src/sqlite.ts +6 -0
  96. package/src/test.ts +15 -3
  97. package/src/testHelpers.ts +16 -7
  98. package/src/testHook.ts +31 -0
  99. package/src/testing.ts +5 -4
  100. package/src/twoFactor.ts +9 -18
  101. package/src/viewer.ts +26 -4
  102. package/types/account.d.ts +10 -23
  103. package/types/account.d.ts.map +1 -1
  104. package/types/admin.d.ts +21 -39
  105. package/types/admin.d.ts.map +1 -1
  106. package/types/auth.d.ts +18 -5
  107. package/types/auth.d.ts.map +1 -1
  108. package/types/authorize/grants.d.ts +2 -5
  109. package/types/authorize/grants.d.ts.map +1 -1
  110. package/types/authorize/request.d.ts +3 -5
  111. package/types/authorize/request.d.ts.map +1 -1
  112. package/types/bearer.d.ts +9 -17
  113. package/types/bearer.d.ts.map +1 -1
  114. package/types/captcha.d.ts +3 -1
  115. package/types/captcha.d.ts.map +1 -1
  116. package/types/context.d.ts +1 -1
  117. package/types/deletion.d.ts +2 -5
  118. package/types/deletion.d.ts.map +1 -1
  119. package/types/email.d.ts +23 -28
  120. package/types/email.d.ts.map +1 -1
  121. package/types/erase.d.ts.map +1 -1
  122. package/types/export.d.ts +3 -5
  123. package/types/export.d.ts.map +1 -1
  124. package/types/failure.d.ts +22 -3
  125. package/types/failure.d.ts.map +1 -1
  126. package/types/guard.d.ts +2 -0
  127. package/types/guard.d.ts.map +1 -1
  128. package/types/guards.d.ts +2 -1
  129. package/types/guards.d.ts.map +1 -1
  130. package/types/index.d.ts +14 -16
  131. package/types/index.d.ts.map +1 -1
  132. package/types/limits.d.ts +57 -1
  133. package/types/limits.d.ts.map +1 -1
  134. package/types/mail.d.ts +5 -0
  135. package/types/mail.d.ts.map +1 -1
  136. package/types/messages/fr.d.ts +1 -0
  137. package/types/methods/account.d.ts +27 -13
  138. package/types/methods/account.d.ts.map +1 -1
  139. package/types/methods/admin.d.ts +39 -15
  140. package/types/methods/admin.d.ts.map +1 -1
  141. package/types/methods/captcha.d.ts +9 -0
  142. package/types/methods/captcha.d.ts.map +1 -0
  143. package/types/methods/email.d.ts +21 -7
  144. package/types/methods/email.d.ts.map +1 -1
  145. package/types/methods/magicLink.d.ts +9 -4
  146. package/types/methods/magicLink.d.ts.map +1 -1
  147. package/types/methods/oauth.d.ts +12 -7
  148. package/types/methods/oauth.d.ts.map +1 -1
  149. package/types/methods/oauthServer.d.ts +13 -5
  150. package/types/methods/oauthServer.d.ts.map +1 -1
  151. package/types/methods/organizations.d.ts +40 -15
  152. package/types/methods/organizations.d.ts.map +1 -1
  153. package/types/methods/passkeys.d.ts +18 -7
  154. package/types/methods/passkeys.d.ts.map +1 -1
  155. package/types/methods/password.d.ts +23 -10
  156. package/types/methods/password.d.ts.map +1 -1
  157. package/types/methods/proof.d.ts +12 -0
  158. package/types/methods/proof.d.ts.map +1 -0
  159. package/types/methods/sessions.d.ts +3 -2
  160. package/types/methods/sessions.d.ts.map +1 -1
  161. package/types/methods/tokens.d.ts +12 -5
  162. package/types/methods/tokens.d.ts.map +1 -1
  163. package/types/methods/twoFactor.d.ts +22 -10
  164. package/types/methods/twoFactor.d.ts.map +1 -1
  165. package/types/oauth/flow.d.ts +4 -6
  166. package/types/oauth/flow.d.ts.map +1 -1
  167. package/types/oauthTest.d.ts +2 -0
  168. package/types/oauthTest.d.ts.map +1 -1
  169. package/types/organizations.d.ts +24 -48
  170. package/types/organizations.d.ts.map +1 -1
  171. package/types/own.d.ts +1 -1
  172. package/types/own.d.ts.map +1 -1
  173. package/types/pages/forms.d.ts +5 -3
  174. package/types/pages/forms.d.ts.map +1 -1
  175. package/types/pages/index.d.ts +5 -2
  176. package/types/pages/index.d.ts.map +1 -1
  177. package/types/passkeys.d.ts +20 -27
  178. package/types/passkeys.d.ts.map +1 -1
  179. package/types/password.d.ts +13 -20
  180. package/types/password.d.ts.map +1 -1
  181. package/types/profile.d.ts +1 -4
  182. package/types/profile.d.ts.map +1 -1
  183. package/types/proof.d.ts +1 -4
  184. package/types/proof.d.ts.map +1 -1
  185. package/types/request.d.ts +33 -7
  186. package/types/request.d.ts.map +1 -1
  187. package/types/requiredTwoFactor.d.ts +3 -1
  188. package/types/requiredTwoFactor.d.ts.map +1 -1
  189. package/types/routes.d.ts +3 -1
  190. package/types/routes.d.ts.map +1 -1
  191. package/types/sessions.d.ts +3 -10
  192. package/types/sessions.d.ts.map +1 -1
  193. package/types/setup.d.ts.map +1 -1
  194. package/types/sqlite.d.ts +3 -0
  195. package/types/sqlite.d.ts.map +1 -0
  196. package/types/test.d.ts +4 -1
  197. package/types/test.d.ts.map +1 -1
  198. package/types/testHelpers.d.ts +1 -0
  199. package/types/testHelpers.d.ts.map +1 -1
  200. package/types/testHook.d.ts +15 -0
  201. package/types/testHook.d.ts.map +1 -0
  202. package/types/testing.d.ts.map +1 -1
  203. package/types/twoFactor.d.ts +10 -21
  204. package/types/twoFactor.d.ts.map +1 -1
  205. package/types/viewer.d.ts +3 -1
  206. package/types/viewer.d.ts.map +1 -1
@@ -1,4 +1,5 @@
1
- import type { AcceptResult, CreateOrganizationResult, DeleteOrganizationResult, Invitation, InviteResult, ListInvitationsResult, ListMembersResult, MemberResult, Membership, RejectInvitationResult, RevokeInvitationResult, UpdateOrganizationResult } from '../organizations'
1
+ import type { Result } from '../failure'
2
+ import type { AuthMember, Invitation, Membership, Organization, OrganizationFailure, OrganizationWriteFailure } from '../organizations'
2
3
  import type { RequestState } from '../state'
3
4
  import { failed } from '../failure'
4
5
  import { load } from '../load'
@@ -8,8 +9,8 @@ export class OrganizationMethods<OrgRole extends string = string> {
8
9
  constructor(private readonly state: RequestState) {}
9
10
 
10
11
  // A new organization, the signed-in user its owner. `slug`, lowercase letters, digits and dashes, names it in URLs.
11
- async create(input: { name: string, slug?: string | null | undefined }): Promise<CreateOrganizationResult<OrgRole>> {
12
- return (await load.organizations()).createOrganization(this.state, input) as Promise<CreateOrganizationResult<OrgRole>>
12
+ async create(input: { name: string, slug?: string | null | undefined }): Promise<Result<{ membership: Membership<OrgRole> }, 'signed-out' | 'impersonating' | 'forbidden' | 'invalid-name' | 'invalid-slug' | 'slug-taken' | 'limited'>> {
13
+ return (await load.organizations()).createOrganization(this.state, input) as Promise<Result<{ membership: Membership<OrgRole> }, 'signed-out' | 'impersonating' | 'forbidden' | 'invalid-name' | 'invalid-slug' | 'slug-taken' | 'limited'>>
13
14
  }
14
15
 
15
16
  // The organizations the signed-in user belongs to, with their roles in each.
@@ -30,67 +31,97 @@ export class OrganizationMethods<OrgRole extends string = string> {
30
31
  }
31
32
 
32
33
  // Renames it, or changes or clears its slug: for members holding `manage`.
33
- async update(ref: string, patch: { name?: string | undefined, slug?: string | null | undefined }): Promise<UpdateOrganizationResult> {
34
+ async update(ref: string, patch: { name?: string | undefined, slug?: string | null | undefined }): Promise<Result<{ organization: Organization }, OrganizationWriteFailure | 'invalid-name' | 'invalid-slug' | 'slug-taken'>> {
34
35
  return (await load.organizations()).updateOrganization(this.state, ref, patch)
35
36
  }
36
37
 
37
38
  // For members holding `owner`.
38
- async delete(ref: string): Promise<DeleteOrganizationResult> {
39
+ async delete(ref: string): Promise<Result<object, OrganizationWriteFailure>> {
39
40
  return (await load.organizations()).deleteOrganization(this.state, ref)
40
41
  }
41
42
 
42
43
  // Every member, oldest first, for any member to see.
43
- async members(ref: string): Promise<ListMembersResult<OrgRole>> {
44
- return (await load.organizations()).listMembers(this.state, ref) as Promise<ListMembersResult<OrgRole>>
44
+ async listMembers(ref: string): Promise<Result<{ members: AuthMember<OrgRole>[] }, OrganizationFailure>> {
45
+ return (await load.organizations()).listMembers(this.state, ref) as Promise<Result<{ members: AuthMember<OrgRole>[] }, OrganizationFailure>>
45
46
  }
46
47
 
47
48
  // Replaces a member's roles: for members holding `manage`, giving only roles they hold, to a member holding none above theirs.
48
- async setMemberRoles(ref: string, userId: string, roles: OrgRole[]): Promise<MemberResult> {
49
+ async updateMemberRoles(ref: string, userId: string, roles: OrgRole[]): Promise<Result<object, OrganizationWriteFailure | 'unknown-role' | 'last-owner'>> {
49
50
  return (await load.organizations()).setMemberRoles(this.state, ref, userId, roles)
50
51
  }
51
52
 
52
53
  // For members holding `manage`, of a member holding no role above theirs.
53
- async removeMember(ref: string, userId: string): Promise<MemberResult> {
54
+ async deleteMember(ref: string, userId: string): Promise<Result<object, OrganizationWriteFailure | 'unknown-role' | 'last-owner'>> {
54
55
  return (await load.organizations()).removeMember(this.state, ref, userId)
55
56
  }
56
57
 
57
- async leave(ref: string): Promise<MemberResult> {
58
+ async leave(ref: string): Promise<Result<object, OrganizationWriteFailure | 'unknown-role' | 'last-owner'>> {
58
59
  const record = await this.state.current()
59
60
 
60
61
  return record ? (await load.organizations()).removeMember(this.state, ref, record.id) : failed('signed-out')
61
62
  }
62
63
 
63
64
  // Mails `email` a link to the `invitationPage`, else the prebuilt pages' invitation page, giving `roles` (`defaultRoles` when none) once accepted: for members holding `manage` and every role it gives.
64
- async invite(ref: string, email: string, roles?: OrgRole[]): Promise<InviteResult<OrgRole>> {
65
- return (await load.organizations()).invite(this.state, ref, email, roles) as Promise<InviteResult<OrgRole>>
65
+ async invite(ref: string, email: string, roles?: OrgRole[]): Promise<Result<{ invitation: Invitation<OrgRole> }, OrganizationWriteFailure | 'unverified' | 'unknown-role' | 'invalid-email' | 'member' | 'limited' | 'unavailable'>> {
66
+ return (await load.organizations()).invite(this.state, ref, email, roles) as Promise<Result<{ invitation: Invitation<OrgRole> }, OrganizationWriteFailure | 'unverified' | 'unknown-role' | 'invalid-email' | 'member' | 'limited' | 'unavailable'>>
66
67
  }
67
68
 
68
69
  // The organization's open invitations, for members holding `manage`.
69
- async invitations(ref: string): Promise<ListInvitationsResult<OrgRole>> {
70
- return (await load.organizations()).listInvitations(this.state, ref) as Promise<ListInvitationsResult<OrgRole>>
70
+ async listInvitations(ref: string): Promise<Result<{ invitations: Invitation<OrgRole>[] }, OrganizationFailure>> {
71
+ return (await load.organizations()).listInvitations(this.state, ref) as Promise<Result<{ invitations: Invitation<OrgRole>[] }, OrganizationFailure>>
71
72
  }
72
73
 
73
- async revokeInvitation(ref: string, invitationId: string): Promise<RevokeInvitationResult> {
74
+ async revokeInvitation(ref: string, invitationId: string): Promise<Result<object, OrganizationWriteFailure>> {
74
75
  return (await load.organizations()).revokeInvitation(this.state, ref, invitationId)
75
76
  }
76
77
 
77
78
  // The invitations open to the signed-in user's verified address.
78
- async myInvitations(): Promise<Invitation<OrgRole>[]> {
79
+ async listMyInvitations(): Promise<Invitation<OrgRole>[]> {
79
80
  return (await load.organizations()).myInvitations(this.state) as Promise<Invitation<OrgRole>[]>
80
81
  }
81
82
 
82
83
  // What the invitation link's page shows; null once revoked, accepted or expired.
83
- async invitation(invitationId: string): Promise<Invitation<OrgRole> | null> {
84
+ async getInvitation(invitationId: string): Promise<Invitation<OrgRole> | null> {
84
85
  return (await load.organizations()).getInvitation(this.state, invitationId) as Promise<Invitation<OrgRole> | null>
85
86
  }
86
87
 
87
88
  // For an account verified at the invited address only.
88
- async acceptInvitation(invitationId: string): Promise<AcceptResult<OrgRole>> {
89
- return (await load.organizations()).acceptInvitation(this.state, invitationId) as Promise<AcceptResult<OrgRole>>
89
+ async acceptInvitation(invitationId: string): Promise<Result<{ membership: Membership<OrgRole> }, 'signed-out' | 'impersonating' | 'not-found' | 'wrong-account' | 'unverified' | 'member'>> {
90
+ return (await load.organizations()).acceptInvitation(this.state, invitationId) as Promise<Result<{ membership: Membership<OrgRole> }, 'signed-out' | 'impersonating' | 'not-found' | 'wrong-account' | 'unverified' | 'member'>>
90
91
  }
91
92
 
92
93
  // Turns down an invitation open to the user; `not-found` for any other.
93
- async rejectInvitation(invitationId: string): Promise<RejectInvitationResult> {
94
+ async rejectInvitation(invitationId: string): Promise<Result<object, 'signed-out' | 'impersonating' | 'not-found'>> {
94
95
  return (await load.organizations()).declineInvitation(this.state, invitationId)
95
96
  }
97
+
98
+ /** @deprecated Use `organizations.listMembers`. Removed in 1.108.0; `deprecated-auth-methods` rewrites it. */
99
+ async members(...args: Parameters<OrganizationMethods<OrgRole>['listMembers']>): ReturnType<OrganizationMethods<OrgRole>['listMembers']> {
100
+ return this.listMembers(...args)
101
+ }
102
+
103
+ /** @deprecated Use `organizations.updateMemberRoles`. Removed in 1.108.0; `deprecated-auth-methods` rewrites it. */
104
+ async setMemberRoles(...args: Parameters<OrganizationMethods<OrgRole>['updateMemberRoles']>): ReturnType<OrganizationMethods<OrgRole>['updateMemberRoles']> {
105
+ return this.updateMemberRoles(...args)
106
+ }
107
+
108
+ /** @deprecated Use `organizations.deleteMember`. Removed in 1.108.0; `deprecated-auth-methods` rewrites it. */
109
+ async removeMember(...args: Parameters<OrganizationMethods<OrgRole>['deleteMember']>): ReturnType<OrganizationMethods<OrgRole>['deleteMember']> {
110
+ return this.deleteMember(...args)
111
+ }
112
+
113
+ /** @deprecated Use `organizations.listInvitations`. Removed in 1.108.0; `deprecated-auth-methods` rewrites it. */
114
+ async invitations(...args: Parameters<OrganizationMethods<OrgRole>['listInvitations']>): ReturnType<OrganizationMethods<OrgRole>['listInvitations']> {
115
+ return this.listInvitations(...args)
116
+ }
117
+
118
+ /** @deprecated Use `organizations.listMyInvitations`. Removed in 1.108.0; `deprecated-auth-methods` rewrites it. */
119
+ async myInvitations(...args: Parameters<OrganizationMethods<OrgRole>['listMyInvitations']>): ReturnType<OrganizationMethods<OrgRole>['listMyInvitations']> {
120
+ return this.listMyInvitations(...args)
121
+ }
122
+
123
+ /** @deprecated Use `organizations.getInvitation`. Removed in 1.108.0; `deprecated-auth-methods` rewrites it. */
124
+ async invitation(...args: Parameters<OrganizationMethods<OrgRole>['getInvitation']>): ReturnType<OrganizationMethods<OrgRole>['getInvitation']> {
125
+ return this.getInvitation(...args)
126
+ }
96
127
  }
@@ -1,5 +1,6 @@
1
1
  import type { Off } from '../core'
2
- import type { Passkey, PasskeyOptionsResult, PasskeySignInResult, RegisterPasskeyResult, RenamePasskeyResult, RevokePasskeyResult } from '../passkeys'
2
+ import type { Result } from '../failure'
3
+ import type { Passkey } from '../passkeys'
3
4
  import type { Proof, ProofFailure } from '../proof'
4
5
  import type { SignInOptions } from '../signInOptions'
5
6
  import type { RequestState } from '../state'
@@ -14,12 +15,12 @@ export class PasskeyMethods {
14
15
  constructor(private readonly state: RequestState) {}
15
16
 
16
17
  // The options for `makePasskey` of `@kayjs/auth/browser`, to make a passkey for the signed-in user once `proof` re-proves them, the second factor when it is on.
17
- async registrationOptions(proof: Proof): Promise<PasskeyOptionsResult<PublicKeyCredentialCreationOptionsJSON, ProofFailure | 'off'>> {
18
+ async registrationOptions(proof: Proof): Promise<Result<{ options: PublicKeyCredentialCreationOptionsJSON }, ProofFailure | 'off'>> {
18
19
  return !this.state.core.switches.passkeys ? OFF : (await load.passkeys()).passkeyRegistrationOptions(this.state, proof)
19
20
  }
20
21
 
21
22
  // Keeps the passkey `makePasskey` made, under `name` or the browser and system it was made on.
22
- async register(response: RegistrationResponseJSON, name?: string): Promise<RegisterPasskeyResult | Off> {
23
+ async register(response: RegistrationResponseJSON, name?: string): Promise<Result<{ passkey: Passkey }, 'signed-out' | 'expired' | 'invalid'> | Off> {
23
24
  return !this.state.core.switches.passkeys ? OFF : (await load.passkeys()).registerPasskey(this.state, response, name)
24
25
  }
25
26
 
@@ -28,11 +29,11 @@ export class PasskeyMethods {
28
29
  }
29
30
 
30
31
  // Renames one of the signed-in user's passkeys; refused with `not-found` for one that is not theirs and `invalid-name` for a blank name.
31
- async rename(id: string, name: string): Promise<RenamePasskeyResult> {
32
+ async update(id: string, name: string): Promise<Result<object, 'signed-out' | 'not-found' | 'invalid-name'>> {
32
33
  return (await load.passkeys()).renamePasskey(this.state, id, name)
33
34
  }
34
35
 
35
- async revoke(id: string, proof: Proof): Promise<RevokePasskeyResult> {
36
+ async revoke(id: string, proof: Proof): Promise<Result<object, ProofFailure | 'not-found' | 'last-way-in'>> {
36
37
  return (await load.passkeys()).removePasskey(this.state, id, proof)
37
38
  }
38
39
 
@@ -45,7 +46,7 @@ export class PasskeyMethods {
45
46
  }
46
47
 
47
48
  // Signs in with the passkey that answered `signInOptions`, with no second factor after it.
48
- async signIn(response: AuthenticationResponseJSON, options: Pick<SignInOptions, 'redirect' | 'remember'> = {}): Promise<PasskeySignInResult | Off> {
49
+ async signIn(response: AuthenticationResponseJSON, options: Pick<SignInOptions, 'redirect' | 'remember'> = {}): Promise<Result<{ redirect: string }, 'expired' | 'invalid' | 'limited' | 'banned'> | Off> {
49
50
  if (!this.state.core.switches.passkeys)
50
51
  return OFF
51
52
 
@@ -55,7 +56,12 @@ export class PasskeyMethods {
55
56
  }
56
57
 
57
58
  // The options for re-proving with a passkey, its answer then passed as `{ passkey }` wherever a proof is asked.
58
- async proofOptions(): Promise<PasskeyOptionsResult<PublicKeyCredentialRequestOptionsJSON>> {
59
+ async proofOptions(): Promise<Result<{ options: PublicKeyCredentialRequestOptionsJSON }, 'signed-out' | 'none' | 'expired' | 'off'>> {
59
60
  return !this.state.core.switches.passkeys ? OFF : (await load.passkeys()).passkeyProofOptions(this.state)
60
61
  }
62
+
63
+ /** @deprecated Use `passkeys.update`. Removed in 1.108.0; `deprecated-auth-methods` rewrites it. */
64
+ async rename(...args: Parameters<PasskeyMethods['update']>): ReturnType<PasskeyMethods['update']> {
65
+ return this.update(...args)
66
+ }
61
67
  }
@@ -1,8 +1,8 @@
1
- import type { ChangePasswordResult } from '../account'
2
- import type { Off } from '../core'
3
- import type { MailRequestResult, ResetPasswordResult } from '../email'
4
- import type { PasswordSignInInput, PasswordSignInResult, RegisterInput, RegisterResult } from '../password'
5
- import type { Proof } from '../proof'
1
+ import type { BareUser, Off } from '../core'
2
+ import type { Result } from '../failure'
3
+ import type { PasswordSignInInput, RegisterErrors, RegisterInput } from '../password'
4
+ import type { Proof, ProofFailure } from '../proof'
5
+ import type { PasswordProblem } from '../rules'
6
6
  import type { SignInOptions } from '../signInOptions'
7
7
  import type { RequestState } from '../state'
8
8
  import { OFF } from '../core'
@@ -14,7 +14,7 @@ export class PasswordMethods {
14
14
  constructor(private readonly state: RequestState) {}
15
15
 
16
16
  // A new user with an email and a password, signed in on this session; field errors come back as codes. With `redirect`, the mail verifying the address leads on to that page.
17
- async register(input: RegisterInput, options?: Pick<SignInOptions, 'remember' | 'captcha' | 'redirect'>): Promise<RegisterResult | Off> {
17
+ async register(input: RegisterInput, options?: Pick<SignInOptions, 'remember' | 'captcha' | 'redirect'>): Promise<Result<{ user: BareUser, signedIn: true } | { signedIn: false }, 'limited' | 'captcha' | 'off', RegisterErrors> | Off> {
18
18
  if (!this.state.core.switches.password)
19
19
  return OFF
20
20
 
@@ -24,7 +24,7 @@ export class PasswordMethods {
24
24
  }
25
25
 
26
26
  // Signs in with an email or a username and a password; a wrong password and an unknown account answer alike.
27
- async signIn(input: PasswordSignInInput, options?: SignInOptions): Promise<PasswordSignInResult | Off> {
27
+ async signIn(input: PasswordSignInInput, options?: SignInOptions): Promise<Result<{ redirect: string }, 'invalid' | 'limited' | 'captcha' | 'unverified' | 'banned'> | Off> {
28
28
  if (!this.state.core.switches.password)
29
29
  return OFF
30
30
 
@@ -34,7 +34,7 @@ export class PasswordMethods {
34
34
  }
35
35
 
36
36
  // Mails a reset link to that address when an account has it; answers alike when none does. The reset signs in to `redirect` when given.
37
- async requestReset(email: string, options: Pick<SignInOptions, 'captcha' | 'redirect'> = {}): Promise<MailRequestResult | Off> {
37
+ async requestReset(email: string, options: Pick<SignInOptions, 'captcha' | 'redirect'> = {}): Promise<Result<object, 'limited' | 'captcha' | 'unavailable'> | Off> {
38
38
  if (!this.state.core.switches.password)
39
39
  return OFF
40
40
 
@@ -42,12 +42,12 @@ export class PasswordMethods {
42
42
  }
43
43
 
44
44
  // Spends a reset link's token on a new password, signing the user out everywhere else and in here.
45
- async reset(token: string, password: string): Promise<ResetPasswordResult | Off> {
45
+ async reset(token: string, password: string): Promise<Result<{ redirect: string }, 'invalid' | 'limited' | 'banned', { password: PasswordProblem | 'breached' }> | Off> {
46
46
  return !this.state.core.switches.password ? OFF : (await load.email()).resetPassword(this.state, token, password)
47
47
  }
48
48
 
49
49
  // Sets the signed-in user's password, or a first one, and ends their other sessions.
50
- async change(proof: Proof, password: string): Promise<ChangePasswordResult | Off> {
50
+ async change(proof: Proof, password: string): Promise<Result<object, ProofFailure, { password: PasswordProblem | 'breached' }> | Off> {
51
51
  return !this.state.core.switches.password ? OFF : (await load.account()).changePassword(this.state, proof, password)
52
52
  }
53
53
  }
@@ -0,0 +1,22 @@
1
+ import type { Duration } from 'kay'
2
+ import type { Result } from '../failure'
3
+ import type { Proof, ProofFailure } from '../proof'
4
+ import type { RequestState } from '../state'
5
+ import { provedLately, reprove } from '../proof'
6
+
7
+ // `auth.proof`: whether the signed-in user proved themselves lately, and proving again before an app's own sensitive change.
8
+ export class ProofMethods {
9
+ constructor(private readonly state: RequestState, private readonly milliseconds: (fresh: Duration) => number) {}
10
+
11
+ // Whether this session signed in or re-proved its user within `fresh`, a duration such as `'5m'` (ten minutes when left out, as `account.export()` and the admin methods ask), for a page to show a form for `renew` first. A bearer token has no session to prove with, so it never has.
12
+ async recent(fresh?: Duration): Promise<boolean> {
13
+ return provedLately(this.state, fresh === undefined ? undefined : this.milliseconds(fresh))
14
+ }
15
+
16
+ // Re-proves the signed-in user, as before an app's own sensitive change: a proof counts for ten minutes, as a sign-in does.
17
+ async renew(proof: Proof): Promise<Result<object, ProofFailure>> {
18
+ const proved = await reprove(this.state, proof)
19
+
20
+ return proved.ok ? { ok: true } : proved
21
+ }
22
+ }
@@ -1,4 +1,5 @@
1
- import type { RevokeSessionResult, UserSession } from '../sessions'
1
+ import type { Result } from '../failure'
2
+ import type { UserSession } from '../sessions'
2
3
  import type { RequestState } from '../state'
3
4
  import { listSessions, revokeSession } from '../sessions'
4
5
 
@@ -12,7 +13,7 @@ export class SessionMethods {
12
13
  }
13
14
 
14
15
  // Ends one of the signed-in user's sessions, effective on its next request; ending this one signs out. Refused with `not-found` when they have none with that id, and `signed-out` through a bearer token.
15
- async revoke(id: string): Promise<RevokeSessionResult> {
16
+ async revoke(id: string): Promise<Result<object, 'signed-out' | 'not-found'>> {
16
17
  return revokeSession(this.state, id, this.state.signOut)
17
18
  }
18
19
  }
@@ -1,14 +1,26 @@
1
- import type { BearerToken, CreateTokenResult, RevokeTokenResult, TokenOptions } from '../bearer'
2
- import type { Proof } from '../proof'
1
+ import type { BearerToken, TokenOptions, TokenProblem } from '../bearer'
2
+ import type { Result } from '../failure'
3
+ import type { Proof, ProofFailure } from '../proof'
3
4
  import type { RequestState } from '../state'
5
+ import { scopeAllows } from '../gate'
4
6
  import { load } from '../load'
5
7
 
6
8
  // `auth.tokens`: the signed-in user's bearer tokens, for their devices and API clients.
7
9
  export class TokenMethods<Scope extends string = string> {
8
- constructor(private readonly state: RequestState) {}
10
+ constructor(private readonly state: RequestState, private readonly held: () => Promise<string[] | null>) {}
11
+
12
+ // The scopes of the bearer token this request came with; null for a session, or a token with every scope.
13
+ async scopes(): Promise<string[] | null> {
14
+ return this.held()
15
+ }
16
+
17
+ // Whether this request may reach what `scope` guards: a session may, and a token given that scope or every one.
18
+ async hasScope(scope: Scope): Promise<boolean> {
19
+ return scopeAllows(await this.held(), scope)
20
+ }
9
21
 
10
22
  // A bearer token for a device or an API client of the signed-in user, shown this once; minted from a session only, never from another token.
11
- async create(proof: Proof, label: string, options: TokenOptions<Scope> = {}): Promise<CreateTokenResult> {
23
+ async create(proof: Proof, label: string, options: TokenOptions<Scope> = {}): Promise<Result<{ token: string, id: string }, ProofFailure | TokenProblem>> {
12
24
  return (await load.bearer()).createToken(this.state, proof, label, options)
13
25
  }
14
26
 
@@ -18,7 +30,7 @@ export class TokenMethods<Scope extends string = string> {
18
30
  }
19
31
 
20
32
  // Revokes one of the signed-in user's bearer tokens, from a browser session only: `signed-out` through a token, `not-found` for one that is not theirs.
21
- async revoke(id: string): Promise<RevokeTokenResult> {
33
+ async revoke(id: string): Promise<Result<object, 'signed-out' | 'not-found'>> {
22
34
  return (await load.bearer()).revokeToken(this.state, id)
23
35
  }
24
36
  }
@@ -1,8 +1,8 @@
1
1
  import type { Off } from '../core'
2
- import type { PasskeyOptionsResult } from '../passkeys'
3
- import type { Proof } from '../proof'
2
+ import type { Result } from '../failure'
3
+ import type { Proof, ProofFailure } from '../proof'
4
4
  import type { RequestState } from '../state'
5
- import type { DisableTwoFactorResult, EnableTwoFactorResult, RecoveryCodesResult, SetUpTwoFactorResult, TwoFactorResult } from '../twoFactor'
5
+ import type { TwoFactorSetup } from '../twoFactor'
6
6
  import type { AuthenticationResponseJSON, PublicKeyCredentialRequestOptionsJSON } from '../webauthn'
7
7
  import { OFF } from '../core'
8
8
  import { load } from '../load'
@@ -18,26 +18,26 @@ export class TwoFactorMethods {
18
18
  }
19
19
 
20
20
  // Finishes a sign-in waiting for its second factor with an authenticator code or a recovery code.
21
- async verify(code: string): Promise<TwoFactorResult> {
21
+ async verify(code: string): Promise<Result<{ redirect: string }, 'invalid' | 'expired' | 'limited'>> {
22
22
  return (await load.twoFactor()).verifyTwoFactor(this.state, code, this.state.establish)
23
23
  }
24
24
 
25
25
  // A secret for the signed-in user's authenticator, as text and as a QR code; the second factor turns on once `enable` gets a code from it.
26
- async setUp(proof: Proof): Promise<SetUpTwoFactorResult | Off> {
26
+ async setUp(proof: Proof): Promise<Result<{ setup: TwoFactorSetup }, ProofFailure | 'enabled'> | Off> {
27
27
  return !this.state.core.switches.twoFactor ? OFF : (await load.twoFactor()).setUpTwoFactor(this.state, proof)
28
28
  }
29
29
 
30
30
  // Turns the second factor on with a code from the authenticator just set up; answers the recovery codes, to show this once.
31
- async enable(code: string): Promise<EnableTwoFactorResult | Off> {
31
+ async enable(code: string): Promise<Result<{ recoveryCodes: string[] }, 'signed-out' | 'not-set-up' | 'enabled' | 'invalid' | 'limited'> | Off> {
32
32
  return !this.state.core.switches.twoFactor ? OFF : (await load.twoFactor()).enableTwoFactor(this.state, code)
33
33
  }
34
34
 
35
- async disable(proof: Proof): Promise<DisableTwoFactorResult> {
35
+ async disable(proof: Proof): Promise<Result<object, ProofFailure>> {
36
36
  return (await load.twoFactor()).disableTwoFactor(this.state, proof)
37
37
  }
38
38
 
39
39
  // A new set of recovery codes, the old ones void.
40
- async regenerateRecoveryCodes(proof: Proof): Promise<RecoveryCodesResult> {
40
+ async regenerateRecoveryCodes(proof: Proof): Promise<Result<{ recoveryCodes: string[] }, ProofFailure | 'not-enabled'>> {
41
41
  return (await load.twoFactor()).regenerateRecoveryCodes(this.state, proof)
42
42
  }
43
43
 
@@ -49,11 +49,11 @@ export class TwoFactorMethods {
49
49
  }
50
50
 
51
51
  // The options for answering a pending sign-in's second factor with a passkey; `none` when the user has none.
52
- async passkeyOptions(): Promise<PasskeyOptionsResult<PublicKeyCredentialRequestOptionsJSON>> {
52
+ async passkeyOptions(): Promise<Result<{ options: PublicKeyCredentialRequestOptionsJSON }, 'signed-out' | 'none' | 'expired' | 'off'>> {
53
53
  return !this.state.core.switches.passkeys ? OFF : (await load.passkeys()).twoFactorPasskeyOptions(this.state)
54
54
  }
55
55
 
56
- async verifyPasskey(response: AuthenticationResponseJSON): Promise<TwoFactorResult | Off> {
56
+ async verifyPasskey(response: AuthenticationResponseJSON): Promise<Result<{ redirect: string }, 'invalid' | 'expired' | 'limited'> | Off> {
57
57
  if (!this.state.core.switches.passkeys)
58
58
  return OFF
59
59
 
package/src/oauth/flow.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { Core, Profile } from '../core'
2
- import type { AuthFailed } from '../failure'
2
+ import type { Result } from '../failure'
3
3
  import type { Proof, ProofFailure } from '../proof'
4
4
  import type { RequestState } from '../state'
5
5
  import type { IdentityRecord, UserRecord } from '../store'
@@ -36,8 +36,6 @@ export interface OAuthFlow {
36
36
  expires: number
37
37
  }
38
38
 
39
- export type LinkProviderResult = { ok: true, url: string } | AuthFailed<ProofFailure | 'not-found' | 'unavailable'>
40
-
41
39
  // The provider's authorize URL for a sign-in, the flow parked in the session; undefined for a provider the app has not configured.
42
40
  export async function startOAuth(state: RequestState, provider: string, options: { redirect?: string | undefined, remember?: boolean | undefined }): Promise<string | { error: OAuthFailure } | undefined> {
43
41
  if (!state.core.oauth.has(provider))
@@ -61,7 +59,7 @@ export async function startOAuth(state: RequestState, provider: string, options:
61
59
 
62
60
  // The provider's authorize URL for linking it to the signed-in user, once `proof` re-proves them.
63
61
  // A linked provider is a way in that outlives every sign-out, so a stolen session alone may not add one, and the second factor proves it when it is on.
64
- export async function startLink(state: RequestState, provider: string, proof: Proof, redirect: string | undefined): Promise<LinkProviderResult> {
62
+ export async function startLink(state: RequestState, provider: string, proof: Proof, redirect: string | undefined): Promise<Result<{ url: string }, ProofFailure | 'not-found' | 'unavailable'>> {
65
63
  if (!state.core.oauth.has(provider))
66
64
  return failed('not-found')
67
65
 
package/src/oauthTest.ts CHANGED
@@ -1,7 +1,9 @@
1
1
  import type { Elysia } from 'elysia'
2
+ import type { TestSite } from 'kay/test'
2
3
  import type { Core } from './core'
3
4
  import type { OAuthTokens, OAuthUser } from './oauth/types'
4
5
  import { Elysia as ElysiaApp } from 'elysia'
6
+ import { KayError } from 'kay/library'
5
7
  import { OAuthExchangeError } from './oauth/client'
6
8
 
7
9
  // What a stubbed provider answers: the account a sign-in comes back with, or why it fails. `access_denied` is a refused consent, `invalid_grant` a code the provider rejects and `server_error` a provider that is down.
@@ -17,6 +19,8 @@ export interface OAuthTest {
17
19
  // A site with a `fetch`, the one `testSite()` returns, is driven through it; one with only its cookies, through the plugin.
18
20
  export interface OAuthSite {
19
21
  cookies: Bun.CookieMap
22
+ // The site's `joinSignIn`, which takes the auth into `site.signInAs` and `site.signOut`.
23
+ joinSignIn?: TestSite['joinSignIn'] | undefined
20
24
  fetch?: ((path: string) => Promise<Response>) | undefined
21
25
  }
22
26
 
@@ -59,10 +63,10 @@ export function oauthTest(core: Core, plugin: Elysia, site: OAuthSite): OAuthTes
59
63
  const entry = core.oauth.get(provider)
60
64
 
61
65
  if (!entry)
62
- throw new Error(`kayjs-auth: oauth.stub found no provider ${provider} configured, its names are ${[...core.oauth.keys()].join(', ') || 'none'}`)
66
+ throw new KayError('argument-invalid', `kayjs-auth: oauth.stub found no provider ${provider} configured, its names are ${[...core.oauth.keys()].join(', ') || 'none'}`)
63
67
 
64
68
  if ('id' in outcome && outcome.id === '')
65
- throw new Error('kayjs-auth: oauth.stub needs the account\'s id')
69
+ throw new KayError('argument-invalid', 'kayjs-auth: oauth.stub needs the account\'s id')
66
70
 
67
71
  const real = originals.get(entry) ?? entry.client
68
72
  const failure = 'error' in outcome ? new OAuthExchangeError(FAILURE_STATUS[outcome.error], `OAuth token request failed (${provider}): ${outcome.error}`) : undefined
@@ -95,13 +99,13 @@ export function oauthTest(core: Core, plugin: Elysia, site: OAuthSite): OAuthTes
95
99
  const outcome = entry && stubs.get(entry)
96
100
 
97
101
  if (!outcome)
98
- throw new Error(`kayjs-auth: oauth.signIn found no stub for ${provider}: call oauth.stub first`)
102
+ throw new KayError('argument-invalid', `kayjs-auth: oauth.signIn found no stub for ${provider}: call oauth.stub first`)
99
103
 
100
104
  const start = await visit(`${core.prefix}/${provider}${options.redirect === undefined ? '' : `?redirect=${encodeURIComponent(options.redirect)}`}`)
101
105
  const location = start.headers.get('location')
102
106
 
103
107
  if (location === null)
104
- throw new Error(`kayjs-auth: oauth.signIn found no redirect to ${provider}, the sign-in route answered ${start.status}`)
108
+ throw new KayError('argument-invalid', `kayjs-auth: oauth.signIn found no redirect to ${provider}, the sign-in route answered ${start.status}`)
105
109
 
106
110
  const state = encodeURIComponent(new URL(location, 'http://localhost').searchParams.get('state') ?? '')
107
111
  const answer = 'error' in outcome && outcome.error === 'access_denied' ? 'error=access_denied' : 'code=stub-code'
@@ -1,5 +1,5 @@
1
1
  import type { Core } from './core'
2
- import type { AuthFailed } from './failure'
2
+ import type { AuthFailed, Result } from './failure'
3
3
  import type { OrganizationsCore } from './organizationsCore'
4
4
  import type { RequestState } from './state'
5
5
  import type { AuthStore, InvitationRecord, MaybePromise, MemberRecord, OrganizationRecord, UserRecord } from './store'
@@ -55,21 +55,9 @@ export type OrganizationFailure = 'signed-out' | 'not-found' | 'forbidden'
55
55
  // A write adds `impersonating`: an admin acting as the user changes nothing about their organizations.
56
56
  export type OrganizationWriteFailure = OrganizationFailure | 'impersonating'
57
57
 
58
- export type CreateOrganizationResult<Role extends string = string> = { ok: true, membership: Membership<Role> } | AuthFailed<'signed-out' | 'impersonating' | 'forbidden' | 'invalid-name' | 'invalid-slug' | 'slug-taken' | 'limited'>
59
-
60
- export type UpdateOrganizationResult = { ok: true, organization: Organization } | AuthFailed<OrganizationWriteFailure | 'invalid-name' | 'invalid-slug' | 'slug-taken'>
61
-
62
58
  // `last-owner` keeps an organization from being left without one.
63
- export type MemberResult = { ok: true } | AuthFailed<OrganizationWriteFailure | 'unknown-role' | 'last-owner'>
64
-
65
- export type InviteResult<Role extends string = string> = { ok: true, invitation: Invitation<Role> } | AuthFailed<OrganizationWriteFailure | 'unverified' | 'unknown-role' | 'invalid-email' | 'member' | 'limited' | 'unavailable'>
66
-
67
- export type ListMembersResult<Role extends string = string> = { ok: true, members: AuthMember<Role>[] } | AuthFailed<OrganizationFailure>
68
-
69
- export type ListInvitationsResult<Role extends string = string> = { ok: true, invitations: Invitation<Role>[] } | AuthFailed<OrganizationFailure>
70
59
 
71
60
  // `wrong-account` when the signed-in user's address is not the one invited, `unverified` while it is but unproven.
72
- export type AcceptResult<Role extends string = string> = { ok: true, membership: Membership<Role> } | AuthFailed<'signed-out' | 'impersonating' | 'not-found' | 'wrong-account' | 'unverified' | 'member'>
73
61
 
74
62
  interface Found { ok: true, record: UserRecord, organization: OrganizationRecord, member: MemberRecord }
75
63
 
@@ -108,7 +96,7 @@ export async function holdsInOrganization(core: Core, userId: string, ref: strin
108
96
  return member !== undefined && (role === undefined || config.isGranted(role, member.roles))
109
97
  }
110
98
 
111
- export async function createOrganization(state: RequestState, input: { name: string, slug?: string | null | undefined }): Promise<CreateOrganizationResult> {
99
+ export async function createOrganization(state: RequestState, input: { name: string, slug?: string | null | undefined }): Promise<Result<{ membership: Membership<string> }, 'signed-out' | 'impersonating' | 'forbidden' | 'invalid-name' | 'invalid-slug' | 'slug-taken' | 'limited'>> {
112
100
  const { config, store } = organizationsOf(state.core)
113
101
  const record = await state.current()
114
102
 
@@ -182,7 +170,7 @@ export async function getMembership(state: RequestState, ref: string): Promise<M
182
170
  return found.ok ? membership(found.organization, found.member) : null
183
171
  }
184
172
 
185
- export async function updateOrganization(state: RequestState, ref: string, patch: { name?: string | undefined, slug?: string | null | undefined }): Promise<UpdateOrganizationResult> {
173
+ export async function updateOrganization(state: RequestState, ref: string, patch: { name?: string | undefined, slug?: string | null | undefined }): Promise<Result<{ organization: Organization }, OrganizationWriteFailure | 'invalid-name' | 'invalid-slug' | 'slug-taken'>> {
186
174
  const { config, store } = organizationsOf(state.core)
187
175
  const found = await asMember(state, ref, config.manage, 'write')
188
176
 
@@ -219,10 +207,8 @@ export async function updateOrganization(state: RequestState, ref: string, patch
219
207
  return updated ? { ok: true, organization: publicOrganization(updated) } : failed('not-found')
220
208
  }
221
209
 
222
- export type DeleteOrganizationResult = { ok: true } | AuthFailed<OrganizationWriteFailure>
223
-
224
210
  // Owners only, from a session: every membership and invitation goes with it.
225
- export async function deleteOrganization(state: RequestState, ref: string): Promise<DeleteOrganizationResult> {
211
+ export async function deleteOrganization(state: RequestState, ref: string): Promise<Result<object, OrganizationWriteFailure>> {
226
212
  const { config, store } = organizationsOf(state.core)
227
213
  const found = await asMember(state, ref, config.owner, 'write')
228
214
 
@@ -236,7 +222,7 @@ export async function deleteOrganization(state: RequestState, ref: string): Prom
236
222
  }
237
223
 
238
224
  // Any member may list the others; only one who manages members is given their emails, the others' `email` is null (their own stays).
239
- export async function listMembers(state: RequestState, ref: string): Promise<ListMembersResult> {
225
+ export async function listMembers(state: RequestState, ref: string): Promise<Result<{ members: AuthMember<string>[] }, OrganizationFailure>> {
240
226
  const { config, store } = organizationsOf(state.core)
241
227
  const found = await asMember(state, ref)
242
228
 
@@ -260,7 +246,7 @@ export async function listMembers(state: RequestState, ref: string): Promise<Lis
260
246
  }
261
247
 
262
248
  // From a session only. A manager gives only roles they hold, to a member holding none above theirs: an admin cannot make an owner, nor demote one.
263
- export async function setMemberRoles(state: RequestState, ref: string, userId: string, roles: string[]): Promise<MemberResult> {
249
+ export async function setMemberRoles(state: RequestState, ref: string, userId: string, roles: string[]): Promise<Result<object, OrganizationWriteFailure | 'unknown-role' | 'last-owner'>> {
264
250
  const { config, store } = organizationsOf(state.core)
265
251
  const found = await asMember(state, ref, config.manage, 'write')
266
252
 
@@ -292,7 +278,7 @@ export async function setMemberRoles(state: RequestState, ref: string, userId: s
292
278
  }
293
279
 
294
280
  // From a session only: the signed-in user leaves, or a manager removes a member holding no role above theirs.
295
- export async function removeMember(state: RequestState, ref: string, userId: string): Promise<MemberResult> {
281
+ export async function removeMember(state: RequestState, ref: string, userId: string): Promise<Result<object, OrganizationWriteFailure | 'unknown-role' | 'last-owner'>> {
296
282
  const { config, store } = organizationsOf(state.core)
297
283
  const self = (await state.current())?.id === userId
298
284
  const found = await asMember(state, ref, self ? undefined : config.manage, 'write')
@@ -330,7 +316,7 @@ export function invitationPageOf(core: Core): string | undefined {
330
316
  }
331
317
 
332
318
  // Mails the address a link to the invitation page; an invitation the address already had is replaced.
333
- export async function invite(state: RequestState, ref: string, email: string, roles?: string[]): Promise<InviteResult> {
319
+ export async function invite(state: RequestState, ref: string, email: string, roles?: string[]): Promise<Result<{ invitation: Invitation<string> }, OrganizationWriteFailure | 'unverified' | 'unknown-role' | 'invalid-email' | 'member' | 'limited' | 'unavailable'>> {
334
320
  const { core } = state
335
321
  const { config, store } = organizationsOf(core)
336
322
  const found = await asMember(state, ref, config.manage, 'write')
@@ -398,7 +384,7 @@ export async function invite(state: RequestState, ref: string, email: string, ro
398
384
  }
399
385
 
400
386
  // The organization's invitations still open, oldest first, for its managers; expired ones are left out.
401
- export async function listInvitations(state: RequestState, ref: string): Promise<ListInvitationsResult> {
387
+ export async function listInvitations(state: RequestState, ref: string): Promise<Result<{ invitations: Invitation<string>[] }, OrganizationFailure>> {
402
388
  const { config, store } = organizationsOf(state.core)
403
389
  const found = await asMember(state, ref, config.manage, 'session')
404
390
 
@@ -408,9 +394,7 @@ export async function listInvitations(state: RequestState, ref: string): Promise
408
394
  return { ok: true, invitations: (await standing(config, store, open(await store.invitations.listByOrganization(found.organization.id)))).map(invitation => publicInvitation(invitation, found.organization)) }
409
395
  }
410
396
 
411
- export type RevokeInvitationResult = { ok: true } | AuthFailed<OrganizationWriteFailure>
412
-
413
- export async function revokeInvitation(state: RequestState, ref: string, invitationId: string): Promise<RevokeInvitationResult> {
397
+ export async function revokeInvitation(state: RequestState, ref: string, invitationId: string): Promise<Result<object, OrganizationWriteFailure>> {
414
398
  const { config, store } = organizationsOf(state.core)
415
399
  const found = await asMember(state, ref, config.manage, 'write')
416
400
 
@@ -482,7 +466,7 @@ export async function getInvitation(state: RequestState, invitationId: string):
482
466
  }
483
467
 
484
468
  // Only an account verified at the invited address accepts, so a forwarded link is worth nothing to anyone else.
485
- export async function acceptInvitation(state: RequestState, invitationId: string): Promise<AcceptResult> {
469
+ export async function acceptInvitation(state: RequestState, invitationId: string): Promise<Result<{ membership: Membership<string> }, 'signed-out' | 'impersonating' | 'not-found' | 'wrong-account' | 'unverified' | 'member'>> {
486
470
  const { config, store } = organizationsOf(state.core)
487
471
  const record = await state.current()
488
472
 
@@ -520,10 +504,8 @@ export async function acceptInvitation(state: RequestState, invitationId: string
520
504
  return { ok: true, membership: membership(organization, member) }
521
505
  }
522
506
 
523
- export type RejectInvitationResult = { ok: true } | AuthFailed<'signed-out' | 'impersonating' | 'not-found'>
524
-
525
507
  // The invited user turns it down; `not-found` when it is not open to them, whoever it was meant for.
526
- export async function declineInvitation(state: RequestState, invitationId: string): Promise<RejectInvitationResult> {
508
+ export async function declineInvitation(state: RequestState, invitationId: string): Promise<Result<object, 'signed-out' | 'impersonating' | 'not-found'>> {
527
509
  const { store } = organizationsOf(state.core)
528
510
  const record = await state.current()
529
511
 
@@ -18,7 +18,7 @@ export interface OrganizationsOptions<OrgRole extends string, Role extends strin
18
18
  defaultRoles?: NoInfer<OrgRole>[] | undefined
19
19
  // Who may create an organization, a site role or a predicate; anyone signed in by default.
20
20
  create?: Requirement<BareUser, NoInfer<Role>> | undefined
21
- // The app's page an invitation link opens, the invitation's id in `?invitation=`: it shows `organizations.invitation(id)` and accepts it. The prebuilt pages' own `/auth/invitation` by default; inviting answers 'unavailable' without either.
21
+ // The app's page an invitation link opens, the invitation's id in `?invitation=`: it shows `organizations.getInvitation(id)` and accepts it. The prebuilt pages' own `/auth/invitation` by default; inviting answers 'unavailable' without either.
22
22
  invitationPage?: string | undefined
23
23
  // How long an invitation lasts, `invitations: { maxAge: '7d' }`, a week by default.
24
24
  invitations?: { maxAge?: Duration | undefined } | undefined