@terreno/api 57.18.0 → 57.20.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.
- package/CHANGELOG.md +2071 -2
- package/dist/accountSecurity/accessActions.d.ts +38 -0
- package/dist/accountSecurity/accessActions.js +157 -0
- package/dist/accountSecurity/accountSecurityApp.d.ts +219 -0
- package/dist/accountSecurity/accountSecurityApp.js +438 -0
- package/dist/accountSecurity/accountSecurityService.d.ts +200 -0
- package/dist/accountSecurity/accountSecurityService.js +481 -0
- package/dist/accountSecurity/credentialActions.d.ts +16 -0
- package/dist/accountSecurity/credentialActions.js +189 -0
- package/dist/accountSecurity/membershipActions.d.ts +15 -0
- package/dist/accountSecurity/membershipActions.js +81 -0
- package/dist/accountSecurity/orgSecurityRoutes.d.ts +50 -0
- package/dist/accountSecurity/orgSecurityRoutes.js +149 -0
- package/dist/accountSecurity/securityEventHooks.d.ts +44 -0
- package/dist/accountSecurity/securityEventHooks.js +223 -0
- package/dist/accountSecurity/securityEvents.d.ts +162 -0
- package/dist/accountSecurity/securityEvents.js +114 -0
- package/dist/accountSecurity/securityNotifications.d.ts +125 -0
- package/dist/accountSecurity/securityNotifications.js +333 -0
- package/dist/api.js +38 -6
- package/dist/audit/auditEventModel.d.ts +5 -3
- package/dist/audit/auditEventModel.js +8 -6
- package/dist/audit/processQueue.js +4 -2
- package/dist/audit/record.d.ts +2 -2
- package/dist/audit/record.js +3 -0
- package/dist/authRecovery.js +29 -1
- package/dist/betterAuth.d.ts +179 -10
- package/dist/betterAuthApp.d.ts +15 -0
- package/dist/betterAuthApp.js +23 -0
- package/dist/betterAuthChallengeHeaders.d.ts +37 -0
- package/dist/betterAuthChallengeHeaders.js +180 -0
- package/dist/betterAuthFeatures.d.ts +54 -0
- package/dist/betterAuthFeatures.js +239 -0
- package/dist/betterAuthMethods.d.ts +73 -0
- package/dist/betterAuthMethods.js +55 -0
- package/dist/betterAuthOAuthHandoff.d.ts +10 -2
- package/dist/betterAuthOAuthHandoff.js +222 -24
- package/dist/betterAuthSetPassword.d.ts +33 -0
- package/dist/betterAuthSetPassword.js +166 -0
- package/dist/betterAuthSetup.d.ts +57 -8
- package/dist/betterAuthSetup.js +327 -36
- package/dist/consentApp.d.ts +9 -4
- package/dist/consentApp.js +344 -28
- package/dist/consentStatus.d.ts +60 -0
- package/dist/consentStatus.js +111 -0
- package/dist/errors.d.ts +6 -0
- package/dist/errors.js +41 -2
- package/dist/expressServer.js +3 -2
- package/dist/index.d.ts +14 -2
- package/dist/index.js +23 -3
- package/dist/mcp/oauth.js +151 -11
- package/dist/mcp/oauthMetadata.d.ts +2 -1
- package/dist/mcp/oauthMetadata.js +7 -4
- package/dist/models/consentResponse.js +51 -0
- package/dist/models/mcpOAuthClient.js +78 -2
- package/dist/models/mcpOAuthToken.js +28 -4
- package/dist/orgs/membershipGuards.d.ts +7 -0
- package/dist/orgs/membershipGuards.js +32 -0
- package/dist/orgs/orgsApp.d.ts +19 -1
- package/dist/orgs/orgsApp.js +55 -24
- package/dist/rateLimit/policies.js +8 -0
- package/dist/rbac/access.js +2 -1
- package/dist/rbac/resolve.d.ts +9 -1
- package/dist/rbac/resolve.js +21 -16
- package/dist/rbac/roleManager.d.ts +6 -0
- package/dist/rbac/roleManager.js +8 -7
- package/dist/rbac/roleModel.d.ts +1 -0
- package/dist/rbac/roleModel.js +45 -3
- package/dist/rbac/statements.d.ts +2 -2
- package/dist/rbac/statements.js +10 -1
- package/dist/rbac/types.d.ts +6 -0
- package/dist/rbac/userWriteGuards.js +2 -1
- package/dist/schemaMetadata.js +8 -1
- package/dist/seedRunner.js +7 -2
- package/dist/terrenoApp.d.ts +4 -0
- package/dist/terrenoApp.js +15 -0
- package/dist/tests/models.d.ts +5 -0
- package/dist/tests/models.js +8 -0
- package/dist/types/consentResponse.d.ts +8 -0
- package/dist/types/mcpOAuth.d.ts +35 -2
- package/package.json +6 -3
- package/src/__snapshots__/openApi.test.ts.snap +288 -0
- package/src/__snapshots__/openApiBuilder.test.ts.snap +96 -0
- package/src/accountSecurity/accessActions.test.ts +723 -0
- package/src/accountSecurity/accessActions.ts +173 -0
- package/src/accountSecurity/accountSecurity.test.ts +947 -0
- package/src/accountSecurity/accountSecurityApp.ts +720 -0
- package/src/accountSecurity/accountSecurityService.ts +826 -0
- package/src/accountSecurity/credentialActions.test.ts +867 -0
- package/src/accountSecurity/credentialActions.ts +260 -0
- package/src/accountSecurity/membershipActions.ts +89 -0
- package/src/accountSecurity/orgSecurityRoutes.test.ts +841 -0
- package/src/accountSecurity/orgSecurityRoutes.ts +232 -0
- package/src/accountSecurity/securityEventHooks.ts +294 -0
- package/src/accountSecurity/securityEvents.ts +165 -0
- package/src/accountSecurity/securityNotifications.test.ts +1323 -0
- package/src/accountSecurity/securityNotifications.ts +516 -0
- package/src/api.arrayOperations.test.ts +71 -0
- package/src/api.ts +38 -7
- package/src/audit/auditEventModel.ts +10 -7
- package/src/audit/processQueue.ts +4 -2
- package/src/audit/record.test.ts +15 -0
- package/src/audit/record.ts +10 -2
- package/src/authRecovery.test.ts +23 -0
- package/src/authRecovery.ts +34 -1
- package/src/authRecoveryBetterAuth.test.ts +169 -0
- package/src/betterAuth.ts +194 -8
- package/src/betterAuthApp.ts +32 -0
- package/src/betterAuthChallengeHeaders.test.ts +476 -0
- package/src/betterAuthChallengeHeaders.ts +227 -0
- package/src/betterAuthFeatures.test.ts +489 -0
- package/src/betterAuthFeatures.ts +283 -0
- package/src/betterAuthLinking.test.ts +844 -0
- package/src/betterAuthMethods.test.ts +138 -0
- package/src/betterAuthMethods.ts +98 -0
- package/src/betterAuthOAuthHandoff.test.ts +482 -69
- package/src/betterAuthOAuthHandoff.ts +293 -33
- package/src/betterAuthOAuthProxy.test.ts +421 -0
- package/src/betterAuthPasswordReset.test.ts +190 -0
- package/src/betterAuthSetPassword.test.ts +378 -0
- package/src/betterAuthSetPassword.ts +213 -0
- package/src/betterAuthSetup.test.ts +39 -7
- package/src/betterAuthSetup.ts +457 -38
- package/src/consentApp.test.ts +869 -2
- package/src/consentApp.ts +438 -36
- package/src/consentStatus.test.ts +226 -0
- package/src/consentStatus.ts +171 -0
- package/src/errors.test.ts +81 -0
- package/src/errors.ts +50 -1
- package/src/expressServer.test.ts +29 -0
- package/src/expressServer.ts +3 -2
- package/src/index.ts +30 -0
- package/src/mcp/oauth.test.ts +463 -2
- package/src/mcp/oauth.ts +184 -13
- package/src/mcp/oauthMetadata.ts +5 -2
- package/src/models/consentResponse.ts +53 -0
- package/src/models/mcpOAuthClient.ts +100 -3
- package/src/models/mcpOAuthToken.ts +30 -5
- package/src/orgs/membershipGuards.ts +39 -0
- package/src/orgs/orgRbac.test.ts +1 -1
- package/src/orgs/orgsApp.test.ts +101 -2
- package/src/orgs/orgsApp.ts +69 -28
- package/src/rateLimit/policies.test.ts +53 -0
- package/src/rateLimit/policies.ts +8 -0
- package/src/rbac/access.ts +4 -1
- package/src/rbac/resolve.test.ts +65 -0
- package/src/rbac/resolve.ts +37 -17
- package/src/rbac/roleManager.test.ts +64 -0
- package/src/rbac/roleManager.ts +15 -6
- package/src/rbac/roleModel.test.ts +174 -1
- package/src/rbac/roleModel.ts +66 -3
- package/src/rbac/routes.test.ts +58 -0
- package/src/rbac/statements.test.ts +4 -1
- package/src/rbac/statements.ts +11 -1
- package/src/rbac/types.ts +6 -1
- package/src/rbac/userWriteGuards.test.ts +48 -0
- package/src/rbac/userWriteGuards.ts +5 -2
- package/src/schemaMetadata.test.ts +39 -0
- package/src/schemaMetadata.ts +11 -1
- package/src/seedRunner.test.ts +56 -0
- package/src/seedRunner.ts +7 -2
- package/src/terrenoApp.ts +20 -0
- package/src/tests/accountSecurityTestApp.ts +290 -0
- package/src/tests/betterAuthStubs.ts +188 -0
- package/src/tests/mockOidcProvider.ts +105 -0
- package/src/tests/models.ts +13 -0
- package/src/tests/softwareAuthenticator.ts +183 -0
- package/src/types/consentResponse.ts +8 -0
- package/src/types/mcpOAuth.ts +39 -3
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Access recovery actions: sign a user out everywhere, mail a password reset, disable or enable
|
|
3
|
+
* the account, and issue a set-password link to a legacy user who has no way to sign in.
|
|
4
|
+
*
|
|
5
|
+
* Revoking deletes the user's Better Auth sessions. Bearer clients (native apps, bearer-mode web,
|
|
6
|
+
* sockets) present the session token itself, so they fail on their next request. Cookie clients
|
|
7
|
+
* can keep working for up to Better Auth's 5-minute session cookie cache (Q7).
|
|
8
|
+
*/
|
|
9
|
+
import type { SecurityRouteAction } from "./accountSecurityApp";
|
|
10
|
+
/**
|
|
11
|
+
* The RBAC statement `issue-sign-in-link` needs on top of `user:manageSecurity` (D11). Only
|
|
12
|
+
* `superadmin` holds it by default (through `*`); without RBAC the actor needs `admin: true`.
|
|
13
|
+
*/
|
|
14
|
+
export declare const ISSUE_SIGN_IN_LINK_PERMISSION: {
|
|
15
|
+
readonly user: readonly ["issueSignInLink"];
|
|
16
|
+
};
|
|
17
|
+
/** `POST /:userId/security/revoke-sessions`: sign the user out on every device. */
|
|
18
|
+
export declare const revokeSessionsAction: SecurityRouteAction;
|
|
19
|
+
/**
|
|
20
|
+
* `POST /:userId/security/send-password-reset`: mail the user a Better Auth password-reset link.
|
|
21
|
+
* 501 without `sendMail` or `publicAppUrl`; 409 for a user with no Better Auth account.
|
|
22
|
+
*/
|
|
23
|
+
export declare const sendPasswordResetAction: SecurityRouteAction;
|
|
24
|
+
/**
|
|
25
|
+
* `POST /:userId/security/disable`: set `User.disabled` and revoke every session. A disabled
|
|
26
|
+
* user's remaining credentials are refused on REST (401) and on the socket handshake.
|
|
27
|
+
*/
|
|
28
|
+
export declare const disableAccountAction: SecurityRouteAction;
|
|
29
|
+
/** `POST /:userId/security/enable`: clear `User.disabled` so the user can sign in again. */
|
|
30
|
+
export declare const enableAccountAction: SecurityRouteAction;
|
|
31
|
+
/**
|
|
32
|
+
* `POST /:userId/security/issue-sign-in-link` (platform only, `user:issueSignInLink`): for a
|
|
33
|
+
* legacy User with no Better Auth account and no password (a GitHub-JWT user), create the Better
|
|
34
|
+
* Auth user, link it, and return a single-use set-password link `{url, expiresAt}` for the
|
|
35
|
+
* administrator to hand over. The link is a password-reset token, so Better Auth's
|
|
36
|
+
* `/reset-password` consumes it once. A link that was never used can be issued again.
|
|
37
|
+
*/
|
|
38
|
+
export declare const issueSignInLinkAction: SecurityRouteAction;
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Access recovery actions: sign a user out everywhere, mail a password reset, disable or enable
|
|
4
|
+
* the account, and issue a set-password link to a legacy user who has no way to sign in.
|
|
5
|
+
*
|
|
6
|
+
* Revoking deletes the user's Better Auth sessions. Bearer clients (native apps, bearer-mode web,
|
|
7
|
+
* sockets) present the session token itself, so they fail on their next request. Cookie clients
|
|
8
|
+
* can keep working for up to Better Auth's 5-minute session cookie cache (Q7).
|
|
9
|
+
*/
|
|
10
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
11
|
+
exports.issueSignInLinkAction = exports.enableAccountAction = exports.disableAccountAction = exports.sendPasswordResetAction = exports.revokeSessionsAction = exports.ISSUE_SIGN_IN_LINK_PERMISSION = void 0;
|
|
12
|
+
const errors_1 = require("../errors");
|
|
13
|
+
/**
|
|
14
|
+
* The RBAC statement `issue-sign-in-link` needs on top of `user:manageSecurity` (D11). Only
|
|
15
|
+
* `superadmin` holds it by default (through `*`); without RBAC the actor needs `admin: true`.
|
|
16
|
+
*/
|
|
17
|
+
exports.ISSUE_SIGN_IN_LINK_PERMISSION = { user: ["issueSignInLink"] };
|
|
18
|
+
const NOT_LINKED_TITLE = "User has no Better Auth account";
|
|
19
|
+
const RESET_NOT_CONFIGURED_TITLE = "Password reset email is not configured";
|
|
20
|
+
const SIGN_IN_LINK_NOT_CONFIGURED_TITLE = "Sign-in links are not configured";
|
|
21
|
+
const SIGN_IN_LINK_REFUSALS = {
|
|
22
|
+
"email-taken": {
|
|
23
|
+
detail: "Another Better Auth user already uses this email",
|
|
24
|
+
title: "Email already belongs to another sign-in account",
|
|
25
|
+
},
|
|
26
|
+
"has-password": {
|
|
27
|
+
detail: "The user can sign in with their existing password, which links their account",
|
|
28
|
+
title: "User already has a password",
|
|
29
|
+
},
|
|
30
|
+
linked: {
|
|
31
|
+
detail: "Use send-password-reset for a user who already has a Better Auth account they have used",
|
|
32
|
+
title: "User already has a Better Auth account",
|
|
33
|
+
},
|
|
34
|
+
"no-email": {
|
|
35
|
+
detail: "Add an email to the user before issuing a sign-in link",
|
|
36
|
+
title: "User has no email",
|
|
37
|
+
},
|
|
38
|
+
};
|
|
39
|
+
/** `POST /:userId/security/revoke-sessions`: sign the user out on every device. */
|
|
40
|
+
exports.revokeSessionsAction = {
|
|
41
|
+
id: "revoke-sessions",
|
|
42
|
+
isApplicable: ({ state }) => state.sessions.active > 0,
|
|
43
|
+
isSupported: (features) => features.betterAuth,
|
|
44
|
+
method: "post",
|
|
45
|
+
path: "/revoke-sessions",
|
|
46
|
+
run: async ({ service, target }) => {
|
|
47
|
+
const { jwtRefreshRevoked, revokedCount } = await service.revokeSessions(target);
|
|
48
|
+
return {
|
|
49
|
+
audit: { jwtRefreshRevoked, revokedCount },
|
|
50
|
+
changed: revokedCount > 0 || jwtRefreshRevoked,
|
|
51
|
+
data: { jwtRefreshRevoked, revokedCount },
|
|
52
|
+
};
|
|
53
|
+
},
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* `POST /:userId/security/send-password-reset`: mail the user a Better Auth password-reset link.
|
|
57
|
+
* 501 without `sendMail` or `publicAppUrl`; 409 for a user with no Better Auth account.
|
|
58
|
+
*/
|
|
59
|
+
exports.sendPasswordResetAction = {
|
|
60
|
+
id: "send-password-reset",
|
|
61
|
+
isApplicable: ({ state }) => state.betterAuthLinked,
|
|
62
|
+
isSupported: (features) => features.betterAuth,
|
|
63
|
+
method: "post",
|
|
64
|
+
path: "/send-password-reset",
|
|
65
|
+
run: async ({ service, target }) => {
|
|
66
|
+
const result = await service.sendPasswordReset(target);
|
|
67
|
+
if (result.sent) {
|
|
68
|
+
return { audit: {}, changed: true, data: { sent: true } };
|
|
69
|
+
}
|
|
70
|
+
if (result.reason === "not-configured") {
|
|
71
|
+
throw new errors_1.APIError({
|
|
72
|
+
detail: "Configure sendMail and publicAppUrl in BetterAuthConfig",
|
|
73
|
+
status: 501,
|
|
74
|
+
title: RESET_NOT_CONFIGURED_TITLE,
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
throw new errors_1.ConflictError({
|
|
78
|
+
detail: "Issue a sign-in link instead, which creates the Better Auth account",
|
|
79
|
+
title: NOT_LINKED_TITLE,
|
|
80
|
+
});
|
|
81
|
+
},
|
|
82
|
+
};
|
|
83
|
+
/**
|
|
84
|
+
* `POST /:userId/security/disable`: set `User.disabled` and revoke every session. A disabled
|
|
85
|
+
* user's remaining credentials are refused on REST (401) and on the socket handshake.
|
|
86
|
+
*/
|
|
87
|
+
exports.disableAccountAction = {
|
|
88
|
+
id: "disable",
|
|
89
|
+
isApplicable: ({ state }) => !state.disabled,
|
|
90
|
+
isSupported: (features) => features.disableAccount,
|
|
91
|
+
method: "post",
|
|
92
|
+
path: "/disable",
|
|
93
|
+
// Under the org-admin prefix "disable" suspends the membership instead (Q8, T9).
|
|
94
|
+
platformOnly: true,
|
|
95
|
+
run: async ({ service, target }) => {
|
|
96
|
+
const { changed } = await service.setDisabled(target, true);
|
|
97
|
+
if (!changed) {
|
|
98
|
+
return { changed: false };
|
|
99
|
+
}
|
|
100
|
+
const { jwtRefreshRevoked, revokedCount } = await service.revokeSessions(target);
|
|
101
|
+
return {
|
|
102
|
+
audit: { jwtRefreshRevoked, revokedCount },
|
|
103
|
+
changed: true,
|
|
104
|
+
data: { jwtRefreshRevoked, revokedCount },
|
|
105
|
+
};
|
|
106
|
+
},
|
|
107
|
+
};
|
|
108
|
+
/** `POST /:userId/security/enable`: clear `User.disabled` so the user can sign in again. */
|
|
109
|
+
exports.enableAccountAction = {
|
|
110
|
+
id: "enable",
|
|
111
|
+
isApplicable: ({ state }) => state.disabled,
|
|
112
|
+
isSupported: (features) => features.disableAccount,
|
|
113
|
+
method: "post",
|
|
114
|
+
path: "/enable",
|
|
115
|
+
platformOnly: true,
|
|
116
|
+
run: async ({ service, target }) => service.setDisabled(target, false),
|
|
117
|
+
};
|
|
118
|
+
/**
|
|
119
|
+
* `POST /:userId/security/issue-sign-in-link` (platform only, `user:issueSignInLink`): for a
|
|
120
|
+
* legacy User with no Better Auth account and no password (a GitHub-JWT user), create the Better
|
|
121
|
+
* Auth user, link it, and return a single-use set-password link `{url, expiresAt}` for the
|
|
122
|
+
* administrator to hand over. The link is a password-reset token, so Better Auth's
|
|
123
|
+
* `/reset-password` consumes it once. A link that was never used can be issued again.
|
|
124
|
+
*/
|
|
125
|
+
exports.issueSignInLinkAction = {
|
|
126
|
+
id: "issue-sign-in-link",
|
|
127
|
+
isApplicable: ({ state }) => !state.legacyPassword &&
|
|
128
|
+
(!state.betterAuthLinked ||
|
|
129
|
+
(!state.emailVerified &&
|
|
130
|
+
!state.password &&
|
|
131
|
+
state.providers.length === 0 &&
|
|
132
|
+
state.passkeys.count === 0)),
|
|
133
|
+
isSupported: (features) => features.betterAuth,
|
|
134
|
+
method: "post",
|
|
135
|
+
path: "/issue-sign-in-link",
|
|
136
|
+
platformOnly: true,
|
|
137
|
+
requiredPermission: exports.ISSUE_SIGN_IN_LINK_PERMISSION,
|
|
138
|
+
run: async ({ service, target }) => {
|
|
139
|
+
const result = await service.issueSignInLink(target);
|
|
140
|
+
if (result.issued) {
|
|
141
|
+
// The URL carries the token, so it goes to the administrator and never into the audit log.
|
|
142
|
+
return {
|
|
143
|
+
audit: { betterAuthId: result.betterAuthId, expiresAt: result.expiresAt },
|
|
144
|
+
changed: true,
|
|
145
|
+
data: { expiresAt: result.expiresAt, url: result.url },
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
if (result.reason === "not-configured") {
|
|
149
|
+
throw new errors_1.APIError({
|
|
150
|
+
detail: "Set publicAppUrl in BetterAuthConfig so the link opens the app's reset page",
|
|
151
|
+
status: 501,
|
|
152
|
+
title: SIGN_IN_LINK_NOT_CONFIGURED_TITLE,
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
throw new errors_1.ConflictError(SIGN_IN_LINK_REFUSALS[result.reason]);
|
|
156
|
+
},
|
|
157
|
+
};
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* AccountSecurityApp: per-user security summary and recovery routes for platform staff.
|
|
3
|
+
*
|
|
4
|
+
* A framework plugin with its own Express router (the OrgsApp precedent), not modelRouter
|
|
5
|
+
* actions. `mountSecurityRoutes(router, authorize)` mounts the same handlers under any prefix,
|
|
6
|
+
* so the org-admin prefix (`/orgs/:orgId/members/:userId/security/*`) reuses them with its own
|
|
7
|
+
* authorizer. Each recovery action is one row in the action table; the summary lists only the
|
|
8
|
+
* actions this server supports and that apply to the user.
|
|
9
|
+
*/
|
|
10
|
+
import type express from "express";
|
|
11
|
+
import { type Request, Router } from "express";
|
|
12
|
+
import { type User, type UserModel } from "../auth";
|
|
13
|
+
import type { BetterAuthInstance } from "../betterAuthSetup";
|
|
14
|
+
import type { AnyTerrenoAccess } from "../rbac/types";
|
|
15
|
+
import type { TerrenoApp } from "../terrenoApp";
|
|
16
|
+
import type { TerrenoPlugin } from "../terrenoPlugin";
|
|
17
|
+
import type { MembershipDocument } from "../types/membership";
|
|
18
|
+
import type { OrganizationDocument } from "../types/organization";
|
|
19
|
+
import { type AccountSecurityFeatures, type AccountSecurityService, type AccountSecurityState } from "./accountSecurityService";
|
|
20
|
+
import { type SecurityActionId, type SecurityActionOrg } from "./securityEvents";
|
|
21
|
+
import { type SecurityNotificationsOptions } from "./securityNotifications";
|
|
22
|
+
/** The RBAC statement that grants the platform security routes. */
|
|
23
|
+
export declare const MANAGE_SECURITY_PERMISSION: {
|
|
24
|
+
readonly user: readonly ["manageSecurity"];
|
|
25
|
+
};
|
|
26
|
+
/** Who is acting, and for org-admin routes, the org they act for. */
|
|
27
|
+
export interface SecurityAuthorization {
|
|
28
|
+
actor: User;
|
|
29
|
+
org?: SecurityActionOrg;
|
|
30
|
+
/**
|
|
31
|
+
* Org routes: the organization and each user's own membership in it. The D9 reach check then
|
|
32
|
+
* resolves the actor under `actorMembership` and the target under `targetMembership`, so both
|
|
33
|
+
* are judged with their org-scoped grants. Without it (platform routes) both are resolved
|
|
34
|
+
* outside any org context.
|
|
35
|
+
*/
|
|
36
|
+
orgScope?: SecurityOrgScope;
|
|
37
|
+
}
|
|
38
|
+
/** Each user's own membership in the organization an org route acts for. */
|
|
39
|
+
export interface SecurityOrgScope {
|
|
40
|
+
/** Absent for platform staff acting through the org prefix without a membership. */
|
|
41
|
+
actorMembership?: MembershipDocument;
|
|
42
|
+
organization: OrganizationDocument;
|
|
43
|
+
targetMembership: MembershipDocument;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Decides whether `req.user` may act on `targetUserId`. Throws an `APIError` to refuse: 403 when
|
|
47
|
+
* the caller lacks the right, 404 when the target is out of their reach.
|
|
48
|
+
*/
|
|
49
|
+
export type SecurityAuthorizer = (args: {
|
|
50
|
+
req: Request;
|
|
51
|
+
targetUserId: string;
|
|
52
|
+
}) => Promise<SecurityAuthorization>;
|
|
53
|
+
/** What a security action handler receives. */
|
|
54
|
+
export interface SecurityActionContext {
|
|
55
|
+
actor: User;
|
|
56
|
+
features: AccountSecurityFeatures;
|
|
57
|
+
org?: SecurityActionOrg;
|
|
58
|
+
req: Request;
|
|
59
|
+
service: AccountSecurityService;
|
|
60
|
+
target: User;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* What a handler returns. A `changed: false` result (nothing to do) answers 200 and is not
|
|
64
|
+
* recorded; `data` is merged into the response body.
|
|
65
|
+
*/
|
|
66
|
+
export interface SecurityActionResult {
|
|
67
|
+
/** Extra fields for the AuditEvent `after` (such as which passkey was removed). No secrets. */
|
|
68
|
+
audit?: Record<string, unknown>;
|
|
69
|
+
changed: boolean;
|
|
70
|
+
data?: Record<string, unknown>;
|
|
71
|
+
}
|
|
72
|
+
/** One row of the action table: a recovery route and the rules for listing it. */
|
|
73
|
+
export interface SecurityRouteAction {
|
|
74
|
+
id: SecurityActionId;
|
|
75
|
+
/** Whether the user's current state makes the action worth offering in the summary. */
|
|
76
|
+
isApplicable: (args: {
|
|
77
|
+
features: AccountSecurityFeatures;
|
|
78
|
+
org?: SecurityActionOrg;
|
|
79
|
+
state: AccountSecurityState;
|
|
80
|
+
}) => boolean;
|
|
81
|
+
/** Whether this server can run it at all. Unsupported actions answer 404. */
|
|
82
|
+
isSupported: (features: AccountSecurityFeatures) => boolean;
|
|
83
|
+
method: "delete" | "post";
|
|
84
|
+
/**
|
|
85
|
+
* Only org-admin prefixes run it (such as `suspend-membership`, which needs the `org`).
|
|
86
|
+
* `mountSecurityRoutes` skips it unless the mount passes `includeOrgOnly`, so the platform
|
|
87
|
+
* `/users` prefix never exposes it.
|
|
88
|
+
*/
|
|
89
|
+
orgOnly?: boolean;
|
|
90
|
+
/** Path under `/:userId/security`, such as `/reset-two-factor` or `/passkeys/:passkeyId`. */
|
|
91
|
+
path: string;
|
|
92
|
+
/**
|
|
93
|
+
* Only platform staff may run it. `mountSecurityRoutes` skips it unless the mount passes
|
|
94
|
+
* `includePlatformOnly`, so org-admin prefixes never expose it.
|
|
95
|
+
*/
|
|
96
|
+
platformOnly?: boolean;
|
|
97
|
+
/**
|
|
98
|
+
* An RBAC permission the actor needs on top of the route's authorizer, such as
|
|
99
|
+
* `{user: ["issueSignInLink"]}`. Without RBAC the actor needs `admin: true`. Actions the actor
|
|
100
|
+
* may not run answer 403 and are left out of the summary.
|
|
101
|
+
*/
|
|
102
|
+
requiredPermission?: {
|
|
103
|
+
readonly [resource: string]: readonly string[];
|
|
104
|
+
};
|
|
105
|
+
run: (context: SecurityActionContext) => Promise<SecurityActionResult>;
|
|
106
|
+
}
|
|
107
|
+
export declare const resetTwoFactorAction: SecurityRouteAction;
|
|
108
|
+
/** The built-in action table, in display order. */
|
|
109
|
+
export declare const defaultSecurityActions: () => SecurityRouteAction[];
|
|
110
|
+
/** Options for {@link AccountSecurityApp.mountSecurityRoutes}. */
|
|
111
|
+
export interface MountSecurityRoutesOptions {
|
|
112
|
+
/**
|
|
113
|
+
* Mount and list actions marked `platformOnly` (such as `issue-sign-in-link`). Only the
|
|
114
|
+
* platform mount sets it; org-admin prefixes leave it off.
|
|
115
|
+
*/
|
|
116
|
+
includePlatformOnly?: boolean;
|
|
117
|
+
/**
|
|
118
|
+
* Mount and list actions marked `orgOnly` (such as `suspend-membership`). Only the org-admin
|
|
119
|
+
* prefix (`OrgsApp`) sets it.
|
|
120
|
+
*/
|
|
121
|
+
includeOrgOnly?: boolean;
|
|
122
|
+
/**
|
|
123
|
+
* Path in front of `/:userId/security` on `router`, such as `/:orgId/members`. Put a parent
|
|
124
|
+
* prefix's params here rather than mounting a nested router under them: OpenAPI documents only
|
|
125
|
+
* the params in each leaf route's own path.
|
|
126
|
+
*/
|
|
127
|
+
pathPrefix?: string;
|
|
128
|
+
}
|
|
129
|
+
export interface AccountSecurityAppOptions {
|
|
130
|
+
/** Extra recovery actions, mounted and listed after the built-in ones. */
|
|
131
|
+
actions?: SecurityRouteAction[];
|
|
132
|
+
/**
|
|
133
|
+
* RBAC access control. Platform routes require `user:manageSecurity`. Defaults to the
|
|
134
|
+
* TerrenoApp's `accessControl`; without either, they require `admin: true`.
|
|
135
|
+
*/
|
|
136
|
+
accessControl?: AnyTerrenoAccess;
|
|
137
|
+
/**
|
|
138
|
+
* Pass `false` to run without AuditApp. Otherwise registration throws unless AuditApp is
|
|
139
|
+
* registered, because every recovery action must leave an audit record.
|
|
140
|
+
*/
|
|
141
|
+
audit?: boolean;
|
|
142
|
+
/** Prefix for the platform routes. Defaults to `/users`. */
|
|
143
|
+
basePath?: string;
|
|
144
|
+
/**
|
|
145
|
+
* Security notification emails: every recorded security action (admin recovery and the user's
|
|
146
|
+
* own changes) emails the affected user. On by default whenever `sendMail` is configured; the
|
|
147
|
+
* org name is left out unless `includeOrgName` is true.
|
|
148
|
+
*/
|
|
149
|
+
notifications?: SecurityNotificationsOptions;
|
|
150
|
+
/**
|
|
151
|
+
* Better Auth instance. Defaults to the registered BetterAuthApp's. Required outside
|
|
152
|
+
* TerrenoApp (setupServer); without it every Better Auth feature reads as off.
|
|
153
|
+
*/
|
|
154
|
+
getBetterAuth?: () => BetterAuthInstance | undefined;
|
|
155
|
+
/**
|
|
156
|
+
* App page base for `issue-sign-in-link` URLs (`{publicAppUrl}/resetPassword?token=`). Defaults
|
|
157
|
+
* to the registered BetterAuthApp's `publicAppUrl`.
|
|
158
|
+
*/
|
|
159
|
+
publicAppUrl?: string;
|
|
160
|
+
/** App User model. Defaults to the TerrenoApp's `userModel`. */
|
|
161
|
+
userModel?: UserModel;
|
|
162
|
+
}
|
|
163
|
+
export declare class AccountSecurityApp implements TerrenoPlugin {
|
|
164
|
+
private readonly options;
|
|
165
|
+
private readonly actions;
|
|
166
|
+
private terrenoApp;
|
|
167
|
+
private openApi;
|
|
168
|
+
private readonly service;
|
|
169
|
+
private registered;
|
|
170
|
+
private warnedNoBetterAuth;
|
|
171
|
+
constructor(options?: AccountSecurityAppOptions);
|
|
172
|
+
/** The recovery actions this plugin mounts, in display order. */
|
|
173
|
+
getActions(): readonly SecurityRouteAction[];
|
|
174
|
+
/**
|
|
175
|
+
* Whether `register` has run. A mount elsewhere (OrgsApp) needs a registered instance: only
|
|
176
|
+
* registration checks for AuditApp and wires access control and the user model.
|
|
177
|
+
*/
|
|
178
|
+
isRegistered(): boolean;
|
|
179
|
+
register(app: express.Application, openApi?: unknown, terrenoApp?: TerrenoApp): void;
|
|
180
|
+
/**
|
|
181
|
+
* Mounts `GET {pathPrefix}/:userId/security` and every action route on `router`, each guarded
|
|
182
|
+
* by `authorize`. Pass a prefix's params (such as `/:orgId/members`) as `pathPrefix` so they
|
|
183
|
+
* reach the authorizer and the OpenAPI spec; a router nested under them instead needs
|
|
184
|
+
* `Router({mergeParams: true})` and leaves them out of the spec.
|
|
185
|
+
*/
|
|
186
|
+
mountSecurityRoutes(router: Router, authorize: SecurityAuthorizer, { includeOrgOnly, includePlatformOnly, pathPrefix, }?: MountSecurityRoutesOptions): void;
|
|
187
|
+
/**
|
|
188
|
+
* The shared pipeline step every route runs before its handler: authorize the caller (403),
|
|
189
|
+
* load the target (404), then refuse a target the caller may not act on (403).
|
|
190
|
+
*/
|
|
191
|
+
private resolveTarget;
|
|
192
|
+
/**
|
|
193
|
+
* Refuses (403) acting on yourself, which belongs on your own security screen, and acting on
|
|
194
|
+
* someone who holds any permission you lack, such as a superadmin, so recovery cannot be used
|
|
195
|
+
* to take over a more privileged account.
|
|
196
|
+
*/
|
|
197
|
+
private assertWithinReach;
|
|
198
|
+
/** Platform staff: `user:manageSecurity` under RBAC, otherwise `admin: true`. */
|
|
199
|
+
readonly authorizePlatform: SecurityAuthorizer;
|
|
200
|
+
/** Whether the actor holds the action's `requiredPermission` (or `admin: true` without RBAC). */
|
|
201
|
+
private mayRun;
|
|
202
|
+
private filterPermitted;
|
|
203
|
+
private listActions;
|
|
204
|
+
private docs;
|
|
205
|
+
private assertAuditRegistered;
|
|
206
|
+
/**
|
|
207
|
+
* Emails the affected user about each security action, unless `notifications.enabled` is
|
|
208
|
+
* false. Security actions are process-wide, so one registration owns the emails: the newest
|
|
209
|
+
* one replaces any earlier subscription, and two registered apps never email twice.
|
|
210
|
+
*/
|
|
211
|
+
private subscribeNotifications;
|
|
212
|
+
/** Stops the security notification emails, when this instance owns them (on shutdown). */
|
|
213
|
+
unsubscribeNotifications(): void;
|
|
214
|
+
private resolveMailConfig;
|
|
215
|
+
private resolveAccessControl;
|
|
216
|
+
private resolvePublicAppUrl;
|
|
217
|
+
private resolveBetterAuth;
|
|
218
|
+
private resolveUserModel;
|
|
219
|
+
}
|