@terreno/api 57.19.2 → 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 +393 -0
- 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,162 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Security actions: the names, labels, and recording of every account-security event.
|
|
3
|
+
*
|
|
4
|
+
* Admin recovery actions (AccountSecurityApp routes) and self-service changes (a user linking a
|
|
5
|
+
* provider or turning on 2FA) are recorded the same way: an `AuditEvent` with
|
|
6
|
+
* `source: "security"` through the existing audit recorder, plus an in-process event that
|
|
7
|
+
* listeners (security notification emails) subscribe to.
|
|
8
|
+
*/
|
|
9
|
+
/** Who started a security action: an administrator on someone else's account, or the user. */
|
|
10
|
+
export type SecurityActionOrigin = "admin" | "self";
|
|
11
|
+
export interface SecurityActionDefinition {
|
|
12
|
+
/** Whether the admin UI should confirm before running it. */
|
|
13
|
+
destructive: boolean;
|
|
14
|
+
/** Short label for buttons and audit views. */
|
|
15
|
+
label: string;
|
|
16
|
+
origin: SecurityActionOrigin;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Every security action name. Admin actions are the recovery routes under
|
|
20
|
+
* `/users/:id/security/*` (and the org-admin prefix); self-service actions are recorded when the
|
|
21
|
+
* user changes their own sign-in methods.
|
|
22
|
+
*/
|
|
23
|
+
export declare const SECURITY_ACTIONS: {
|
|
24
|
+
readonly disable: {
|
|
25
|
+
readonly destructive: true;
|
|
26
|
+
readonly label: "Disable account";
|
|
27
|
+
readonly origin: "admin";
|
|
28
|
+
};
|
|
29
|
+
readonly enable: {
|
|
30
|
+
readonly destructive: false;
|
|
31
|
+
readonly label: "Enable account";
|
|
32
|
+
readonly origin: "admin";
|
|
33
|
+
};
|
|
34
|
+
readonly "issue-sign-in-link": {
|
|
35
|
+
readonly destructive: false;
|
|
36
|
+
readonly label: "Issue sign-in link";
|
|
37
|
+
readonly origin: "admin";
|
|
38
|
+
};
|
|
39
|
+
readonly "other-sessions-revoked": {
|
|
40
|
+
readonly destructive: false;
|
|
41
|
+
readonly label: "Other sessions signed out";
|
|
42
|
+
readonly origin: "self";
|
|
43
|
+
};
|
|
44
|
+
readonly "passkey-added": {
|
|
45
|
+
readonly destructive: false;
|
|
46
|
+
readonly label: "Passkey added";
|
|
47
|
+
readonly origin: "self";
|
|
48
|
+
};
|
|
49
|
+
readonly "passkey-removed": {
|
|
50
|
+
readonly destructive: false;
|
|
51
|
+
readonly label: "Passkey removed";
|
|
52
|
+
readonly origin: "self";
|
|
53
|
+
};
|
|
54
|
+
readonly "password-changed": {
|
|
55
|
+
readonly destructive: false;
|
|
56
|
+
readonly label: "Password changed";
|
|
57
|
+
readonly origin: "self";
|
|
58
|
+
};
|
|
59
|
+
readonly "password-reset": {
|
|
60
|
+
readonly destructive: false;
|
|
61
|
+
readonly label: "Password reset with a link";
|
|
62
|
+
readonly origin: "self";
|
|
63
|
+
};
|
|
64
|
+
readonly "password-set": {
|
|
65
|
+
readonly destructive: false;
|
|
66
|
+
readonly label: "Password added";
|
|
67
|
+
readonly origin: "self";
|
|
68
|
+
};
|
|
69
|
+
readonly "provider-linked": {
|
|
70
|
+
readonly destructive: false;
|
|
71
|
+
readonly label: "Sign-in provider linked";
|
|
72
|
+
readonly origin: "self";
|
|
73
|
+
};
|
|
74
|
+
readonly "provider-unlinked": {
|
|
75
|
+
readonly destructive: false;
|
|
76
|
+
readonly label: "Sign-in provider unlinked";
|
|
77
|
+
readonly origin: "self";
|
|
78
|
+
};
|
|
79
|
+
readonly "remove-passkey": {
|
|
80
|
+
readonly destructive: true;
|
|
81
|
+
readonly label: "Remove passkey";
|
|
82
|
+
readonly origin: "admin";
|
|
83
|
+
};
|
|
84
|
+
readonly "reset-two-factor": {
|
|
85
|
+
readonly destructive: true;
|
|
86
|
+
readonly label: "Reset two-factor";
|
|
87
|
+
readonly origin: "admin";
|
|
88
|
+
};
|
|
89
|
+
readonly "revoke-sessions": {
|
|
90
|
+
readonly destructive: true;
|
|
91
|
+
readonly label: "Sign out everywhere";
|
|
92
|
+
readonly origin: "admin";
|
|
93
|
+
};
|
|
94
|
+
readonly "send-password-reset": {
|
|
95
|
+
readonly destructive: false;
|
|
96
|
+
readonly label: "Send password reset";
|
|
97
|
+
readonly origin: "admin";
|
|
98
|
+
};
|
|
99
|
+
readonly "suspend-membership": {
|
|
100
|
+
readonly destructive: true;
|
|
101
|
+
readonly label: "Suspend membership";
|
|
102
|
+
readonly origin: "admin";
|
|
103
|
+
};
|
|
104
|
+
readonly "two-factor-disabled": {
|
|
105
|
+
readonly destructive: false;
|
|
106
|
+
readonly label: "Two-factor turned off";
|
|
107
|
+
readonly origin: "self";
|
|
108
|
+
};
|
|
109
|
+
readonly "two-factor-enabled": {
|
|
110
|
+
readonly destructive: false;
|
|
111
|
+
readonly label: "Two-factor turned on";
|
|
112
|
+
readonly origin: "self";
|
|
113
|
+
};
|
|
114
|
+
readonly "unlink-provider": {
|
|
115
|
+
readonly destructive: true;
|
|
116
|
+
readonly label: "Unlink provider";
|
|
117
|
+
readonly origin: "admin";
|
|
118
|
+
};
|
|
119
|
+
};
|
|
120
|
+
export type SecurityActionId = keyof typeof SECURITY_ACTIONS;
|
|
121
|
+
/** A user named by its app User id. */
|
|
122
|
+
export interface SecurityPrincipal {
|
|
123
|
+
id: string;
|
|
124
|
+
}
|
|
125
|
+
/** The organization whose admin acted, for actions run under the org-admin prefix. */
|
|
126
|
+
export interface SecurityActionOrg {
|
|
127
|
+
id: string;
|
|
128
|
+
name?: string;
|
|
129
|
+
}
|
|
130
|
+
export interface RecordSecurityActionArgs {
|
|
131
|
+
action: SecurityActionId;
|
|
132
|
+
/** Who acted. Omit only when no user is known (a system job). */
|
|
133
|
+
actor?: SecurityPrincipal;
|
|
134
|
+
/** Extra fields for the AuditEvent `after`, such as which passkey or provider. No secrets. */
|
|
135
|
+
details?: Record<string, unknown>;
|
|
136
|
+
org?: SecurityActionOrg;
|
|
137
|
+
/** Whose account changed. */
|
|
138
|
+
target: SecurityPrincipal;
|
|
139
|
+
}
|
|
140
|
+
/** What listeners receive for every recorded security action. */
|
|
141
|
+
export interface SecurityActionEvent extends RecordSecurityActionArgs {
|
|
142
|
+
/** ISO timestamp of when the action was recorded. */
|
|
143
|
+
occurredAt: string;
|
|
144
|
+
origin: SecurityActionOrigin;
|
|
145
|
+
}
|
|
146
|
+
export type SecurityActionListener = (event: SecurityActionEvent) => void | Promise<void>;
|
|
147
|
+
/**
|
|
148
|
+
* Subscribes to every recorded security action (for example, to email the affected user).
|
|
149
|
+
* Returns the unsubscribe function. A throwing listener is logged and never fails the action.
|
|
150
|
+
*/
|
|
151
|
+
export declare const onSecurityAction: (listener: SecurityActionListener) => (() => void);
|
|
152
|
+
export declare const clearSecurityActionListenersForTests: () => void;
|
|
153
|
+
/**
|
|
154
|
+
* Records a security action: one `AuditEvent` (`source: "security"`, `modelName: "User"`,
|
|
155
|
+
* `recordId` the target, `verb: "updated"`, `after: {...details, securityAction,
|
|
156
|
+
* organizationId?}`) when
|
|
157
|
+
* AuditApp is registered, and one event to every {@link onSecurityAction} listener.
|
|
158
|
+
*
|
|
159
|
+
* The audit write follows the recorder's fire-and-forget convention: the returned promise
|
|
160
|
+
* settles when it is persisted (or failed and logged); HTTP handlers do not await it.
|
|
161
|
+
*/
|
|
162
|
+
export declare const recordSecurityAction: ({ action, actor, details, org, target, }: RecordSecurityActionArgs) => Promise<void>;
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Security actions: the names, labels, and recording of every account-security event.
|
|
4
|
+
*
|
|
5
|
+
* Admin recovery actions (AccountSecurityApp routes) and self-service changes (a user linking a
|
|
6
|
+
* provider or turning on 2FA) are recorded the same way: an `AuditEvent` with
|
|
7
|
+
* `source: "security"` through the existing audit recorder, plus an in-process event that
|
|
8
|
+
* listeners (security notification emails) subscribe to.
|
|
9
|
+
*/
|
|
10
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
11
|
+
exports.recordSecurityAction = exports.clearSecurityActionListenersForTests = exports.onSecurityAction = exports.SECURITY_ACTIONS = void 0;
|
|
12
|
+
const luxon_1 = require("luxon");
|
|
13
|
+
const record_1 = require("../audit/record");
|
|
14
|
+
const logger_1 = require("../logger");
|
|
15
|
+
/**
|
|
16
|
+
* Every security action name. Admin actions are the recovery routes under
|
|
17
|
+
* `/users/:id/security/*` (and the org-admin prefix); self-service actions are recorded when the
|
|
18
|
+
* user changes their own sign-in methods.
|
|
19
|
+
*/
|
|
20
|
+
exports.SECURITY_ACTIONS = {
|
|
21
|
+
disable: { destructive: true, label: "Disable account", origin: "admin" },
|
|
22
|
+
enable: { destructive: false, label: "Enable account", origin: "admin" },
|
|
23
|
+
"issue-sign-in-link": { destructive: false, label: "Issue sign-in link", origin: "admin" },
|
|
24
|
+
"other-sessions-revoked": {
|
|
25
|
+
destructive: false,
|
|
26
|
+
label: "Other sessions signed out",
|
|
27
|
+
origin: "self",
|
|
28
|
+
},
|
|
29
|
+
"passkey-added": { destructive: false, label: "Passkey added", origin: "self" },
|
|
30
|
+
"passkey-removed": { destructive: false, label: "Passkey removed", origin: "self" },
|
|
31
|
+
"password-changed": { destructive: false, label: "Password changed", origin: "self" },
|
|
32
|
+
"password-reset": { destructive: false, label: "Password reset with a link", origin: "self" },
|
|
33
|
+
"password-set": { destructive: false, label: "Password added", origin: "self" },
|
|
34
|
+
"provider-linked": { destructive: false, label: "Sign-in provider linked", origin: "self" },
|
|
35
|
+
"provider-unlinked": { destructive: false, label: "Sign-in provider unlinked", origin: "self" },
|
|
36
|
+
"remove-passkey": { destructive: true, label: "Remove passkey", origin: "admin" },
|
|
37
|
+
"reset-two-factor": { destructive: true, label: "Reset two-factor", origin: "admin" },
|
|
38
|
+
"revoke-sessions": { destructive: true, label: "Sign out everywhere", origin: "admin" },
|
|
39
|
+
"send-password-reset": { destructive: false, label: "Send password reset", origin: "admin" },
|
|
40
|
+
"suspend-membership": { destructive: true, label: "Suspend membership", origin: "admin" },
|
|
41
|
+
"two-factor-disabled": { destructive: false, label: "Two-factor turned off", origin: "self" },
|
|
42
|
+
"two-factor-enabled": { destructive: false, label: "Two-factor turned on", origin: "self" },
|
|
43
|
+
"unlink-provider": { destructive: true, label: "Unlink provider", origin: "admin" },
|
|
44
|
+
};
|
|
45
|
+
const listeners = new Set();
|
|
46
|
+
/**
|
|
47
|
+
* Subscribes to every recorded security action (for example, to email the affected user).
|
|
48
|
+
* Returns the unsubscribe function. A throwing listener is logged and never fails the action.
|
|
49
|
+
*/
|
|
50
|
+
const onSecurityAction = (listener) => {
|
|
51
|
+
listeners.add(listener);
|
|
52
|
+
return () => {
|
|
53
|
+
listeners.delete(listener);
|
|
54
|
+
};
|
|
55
|
+
};
|
|
56
|
+
exports.onSecurityAction = onSecurityAction;
|
|
57
|
+
const clearSecurityActionListenersForTests = () => {
|
|
58
|
+
listeners.clear();
|
|
59
|
+
};
|
|
60
|
+
exports.clearSecurityActionListenersForTests = clearSecurityActionListenersForTests;
|
|
61
|
+
const notifyListeners = (event) => {
|
|
62
|
+
for (const listener of listeners) {
|
|
63
|
+
try {
|
|
64
|
+
const result = listener(event);
|
|
65
|
+
if (result instanceof Promise) {
|
|
66
|
+
result.catch((error) => {
|
|
67
|
+
logger_1.logger.error(`Security action listener failed for ${event.action}`, error);
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
catch (error) {
|
|
72
|
+
logger_1.logger.error(`Security action listener failed for ${event.action}`, error);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
};
|
|
76
|
+
/**
|
|
77
|
+
* Records a security action: one `AuditEvent` (`source: "security"`, `modelName: "User"`,
|
|
78
|
+
* `recordId` the target, `verb: "updated"`, `after: {...details, securityAction,
|
|
79
|
+
* organizationId?}`) when
|
|
80
|
+
* AuditApp is registered, and one event to every {@link onSecurityAction} listener.
|
|
81
|
+
*
|
|
82
|
+
* The audit write follows the recorder's fire-and-forget convention: the returned promise
|
|
83
|
+
* settles when it is persisted (or failed and logged); HTTP handlers do not await it.
|
|
84
|
+
*/
|
|
85
|
+
const recordSecurityAction = ({ action, actor, details, org, target, }) => {
|
|
86
|
+
const event = {
|
|
87
|
+
action,
|
|
88
|
+
...(actor ? { actor } : {}),
|
|
89
|
+
...(details ? { details } : {}),
|
|
90
|
+
occurredAt: luxon_1.DateTime.now().toUTC().toISO() ?? "",
|
|
91
|
+
...(org ? { org } : {}),
|
|
92
|
+
origin: exports.SECURITY_ACTIONS[action].origin,
|
|
93
|
+
target,
|
|
94
|
+
};
|
|
95
|
+
notifyListeners(event);
|
|
96
|
+
if (!(0, record_1.isAuditRecorderInstalled)()) {
|
|
97
|
+
return Promise.resolve();
|
|
98
|
+
}
|
|
99
|
+
return (0, record_1.recordAuditEvent)({
|
|
100
|
+
actorId: actor?.id,
|
|
101
|
+
after: {
|
|
102
|
+
...details,
|
|
103
|
+
securityAction: action,
|
|
104
|
+
...(org ? { organizationId: org.id } : {}),
|
|
105
|
+
},
|
|
106
|
+
modelName: "User",
|
|
107
|
+
operation: "update",
|
|
108
|
+
...(org ? { organizationId: org.id } : {}),
|
|
109
|
+
recordId: target.id,
|
|
110
|
+
source: "security",
|
|
111
|
+
verb: "updated",
|
|
112
|
+
});
|
|
113
|
+
};
|
|
114
|
+
exports.recordSecurityAction = recordSecurityAction;
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Security notification emails: one email to the affected user for every recorded security
|
|
3
|
+
* action, whether an administrator ran it or the user did.
|
|
4
|
+
*
|
|
5
|
+
* HIPAA posture: the emails are generic. They name the change and who made it ("you" or "an
|
|
6
|
+
* administrator", never the admin's name or email), never include tokens, links that sign in,
|
|
7
|
+
* passkey names, or other user-chosen text, and name the organization only when the app opts in
|
|
8
|
+
* with `notifications.includeOrgName` (on a shared inbox an org name can reveal care).
|
|
9
|
+
*/
|
|
10
|
+
import type { UserModel } from "../auth";
|
|
11
|
+
import type { BetterAuthConfig } from "../betterAuth";
|
|
12
|
+
import type { SecurityActionEvent, SecurityActionId } from "./securityEvents";
|
|
13
|
+
/** A mail template: `{{name}}` placeholders are filled from the render data. */
|
|
14
|
+
export interface SecurityMailTemplate {
|
|
15
|
+
html?: string;
|
|
16
|
+
subject: string;
|
|
17
|
+
text?: string;
|
|
18
|
+
}
|
|
19
|
+
/** The template ids security notifications render, one per kind of change. */
|
|
20
|
+
export declare const SECURITY_MAIL_TEMPLATE_IDS: readonly ["securityAccountDisabled", "securityAccountEnabled", "securityMembershipSuspended", "securityOtherSessionsRevoked", "securityPasskeyAdded", "securityPasskeyRemoved", "securityPasswordChanged", "securityPasswordReset", "securityPasswordSet", "securityProviderLinked", "securityProviderUnlinked", "securitySessionsRevoked", "securitySignInLinkIssued", "securityTwoFactorDisabled", "securityTwoFactorEnabled"];
|
|
21
|
+
export type SecurityMailTemplateId = (typeof SECURITY_MAIL_TEMPLATE_IDS)[number];
|
|
22
|
+
/**
|
|
23
|
+
* The default notification templates. `@terreno/comms` `DEFAULT_AUTH_MAIL_TEMPLATES` includes
|
|
24
|
+
* them, so `renderAuthMail` renders them too. Data: `actor` ("You" / "An administrator"),
|
|
25
|
+
* `orgClause` ("" or " at {org}"), `orgReference` ("{org}" or "an organization"),
|
|
26
|
+
* `providerName`, `occurredAt`, `appUrl`, and `secureAccountLine`.
|
|
27
|
+
*/
|
|
28
|
+
export declare const DEFAULT_SECURITY_MAIL_TEMPLATES: Record<SecurityMailTemplateId, SecurityMailTemplate>;
|
|
29
|
+
/**
|
|
30
|
+
* Which template each security action sends; every action is listed. `null` sends nothing:
|
|
31
|
+
* `send-password-reset`'s own reset email is the notice, and a second email would be noise.
|
|
32
|
+
* `issue-sign-in-link` emails the user (who always has an email; the action refuses users
|
|
33
|
+
* without one) that a link exists, never the link itself.
|
|
34
|
+
*/
|
|
35
|
+
export declare const SECURITY_NOTIFICATION_TEMPLATES: Record<SecurityActionId, SecurityMailTemplateId | null>;
|
|
36
|
+
/** `notifications` on `AccountSecurityApp`. */
|
|
37
|
+
export interface SecurityNotificationsOptions {
|
|
38
|
+
/**
|
|
39
|
+
* Email the affected user about every security action. Defaults to `true`; nothing is sent
|
|
40
|
+
* while no `sendMail` is configured.
|
|
41
|
+
*/
|
|
42
|
+
enabled?: boolean;
|
|
43
|
+
/**
|
|
44
|
+
* Name the organization in emails about actions an org-admin ran. Defaults to `false`: on a
|
|
45
|
+
* shared inbox the org name can reveal care.
|
|
46
|
+
*/
|
|
47
|
+
includeOrgName?: boolean;
|
|
48
|
+
/**
|
|
49
|
+
* Renders the emails instead of the built-in renderer, for example `@terreno/comms`
|
|
50
|
+
* `renderAuthMail`. Not read from `BetterAuthConfig.renderAuthMail`: a renderer written only
|
|
51
|
+
* for reset and verify mail would answer every security id with one of those. Falls back to
|
|
52
|
+
* the built-in renderer when it throws or returns no subject.
|
|
53
|
+
*/
|
|
54
|
+
render?: SecurityMailRenderer;
|
|
55
|
+
/**
|
|
56
|
+
* Send at most one email per user and template in this many minutes, so a burst of the same
|
|
57
|
+
* change (say, signing out other sessions five times) is one email. Defaults to 10; `0` sends
|
|
58
|
+
* every one. Every action is still recorded in the audit log.
|
|
59
|
+
*/
|
|
60
|
+
throttleMinutes?: number;
|
|
61
|
+
/**
|
|
62
|
+
* Delivers the emails. Defaults to the registered `BetterAuthApp`'s `sendMail`. Set it with
|
|
63
|
+
* `setupServer`, where there is no `BetterAuthApp` to read.
|
|
64
|
+
*/
|
|
65
|
+
sendMail?: BetterAuthConfig["sendMail"];
|
|
66
|
+
}
|
|
67
|
+
/** A renderer for security notification templates (`@terreno/comms` `renderAuthMail` fits). */
|
|
68
|
+
export type SecurityMailRenderer = (options: {
|
|
69
|
+
data: Record<string, string>;
|
|
70
|
+
publicAppUrl: string;
|
|
71
|
+
templateId: SecurityMailTemplateId;
|
|
72
|
+
templates?: Partial<Record<SecurityMailTemplateId, SecurityMailTemplate>>;
|
|
73
|
+
}) => SecurityMailTemplate;
|
|
74
|
+
/** Default `throttleMinutes`. */
|
|
75
|
+
export declare const DEFAULT_SECURITY_NOTIFICATION_THROTTLE_MINUTES = 10;
|
|
76
|
+
/**
|
|
77
|
+
* The placeholder values for one event. Only fixed phrases, the time, the app URL, a known
|
|
78
|
+
* provider name, and (with `includeOrgName`) the organization name: nothing user-chosen, no
|
|
79
|
+
* tokens, and no admin identity.
|
|
80
|
+
*/
|
|
81
|
+
export declare const buildSecurityMailData: ({ event, includeOrgName, publicAppUrl, }: {
|
|
82
|
+
event: SecurityActionEvent;
|
|
83
|
+
includeOrgName?: boolean;
|
|
84
|
+
publicAppUrl?: string;
|
|
85
|
+
}) => Record<string, string>;
|
|
86
|
+
/** Escapes a value for an HTML body, so an org name cannot inject markup. */
|
|
87
|
+
export declare const escapeMailHtml: (value: string) => string;
|
|
88
|
+
/**
|
|
89
|
+
* Renders a security notification without `@terreno/comms`, from `templates` or the defaults.
|
|
90
|
+
* HTML bodies get HTML-escaped values. Matches `renderAuthMail` output for the same input.
|
|
91
|
+
*/
|
|
92
|
+
export declare const renderSecurityMail: ({ data, templateId, templates, }: {
|
|
93
|
+
data: Record<string, string>;
|
|
94
|
+
templateId: SecurityMailTemplateId;
|
|
95
|
+
templates?: Partial<Record<string, SecurityMailTemplate>>;
|
|
96
|
+
}) => SecurityMailTemplate;
|
|
97
|
+
/** The mail settings a notification reads when it is sent. */
|
|
98
|
+
export interface SecurityMailConfig {
|
|
99
|
+
authMailTemplates?: BetterAuthConfig["authMailTemplates"];
|
|
100
|
+
publicAppUrl?: string;
|
|
101
|
+
sendMail?: BetterAuthConfig["sendMail"];
|
|
102
|
+
}
|
|
103
|
+
/** The `onSecurityAction` listener {@link createSecurityNotificationListener} builds. */
|
|
104
|
+
export interface SecurityNotificationListener {
|
|
105
|
+
(event: SecurityActionEvent): Promise<void>;
|
|
106
|
+
/** How many throttle keys are held (expired ones are pruned on each send). */
|
|
107
|
+
throttleEntryCount: () => number;
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Builds the `onSecurityAction` listener that emails the target. Repeats are throttled per
|
|
111
|
+
* target, template, origin (self or admin), and org, so a burst of one change is one email. It sends nothing for actions
|
|
112
|
+
* without a template, when `sendMail` is unset, or when the user has no email. A delivery
|
|
113
|
+
* failure is logged (with the action and user id, never the address) and never fails the action.
|
|
114
|
+
*/
|
|
115
|
+
export declare const createSecurityNotificationListener: ({ getMailConfig, getUserModel, includeOrgName, now, render, throttleMinutes, }: {
|
|
116
|
+
getMailConfig: () => SecurityMailConfig;
|
|
117
|
+
getUserModel: () => UserModel;
|
|
118
|
+
includeOrgName?: boolean;
|
|
119
|
+
/** The current time in epoch milliseconds. Tests pass a fake clock. */
|
|
120
|
+
now?: () => number;
|
|
121
|
+
render?: SecurityMailRenderer;
|
|
122
|
+
throttleMinutes?: number;
|
|
123
|
+
}) => SecurityNotificationListener;
|
|
124
|
+
/** Resolves once every notification started so far has been sent (or failed and been logged). */
|
|
125
|
+
export declare const flushSecurityNotificationsForTests: () => Promise<void>;
|