@hogsend/engine 0.63.0 → 0.65.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/package.json +13 -12
- package/src/account-links/__fixtures__/fake-fetch.test.ts +57 -0
- package/src/account-links/__fixtures__/fake-fetch.ts +114 -0
- package/src/account-links/__fixtures__/steam.json +21 -0
- package/src/account-links/__fixtures__/twitch.json +22 -0
- package/src/account-links/index.ts +8 -0
- package/src/account-links/steam.test.ts +243 -0
- package/src/account-links/steam.ts +48 -0
- package/src/account-links/twitch.test.ts +157 -0
- package/src/account-links/twitch.ts +99 -0
- package/src/container.account-links.env.test.ts +65 -0
- package/src/container.account-links.halfenv.test.ts +48 -0
- package/src/container.account-links.test.ts +185 -0
- package/src/container.ts +120 -0
- package/src/env.ts +60 -0
- package/src/index.ts +104 -1
- package/src/journeys/journey-boundary.ts +8 -0
- package/src/lib/account-link-emit.ts +126 -0
- package/src/lib/account-link-events.ts +180 -0
- package/src/lib/account-link-hooks.test.ts +158 -0
- package/src/lib/account-link-hooks.ts +73 -0
- package/src/lib/account-link-ingest.ts +364 -0
- package/src/lib/account-link-nonce.test.ts +52 -0
- package/src/lib/account-link-nonce.ts +57 -0
- package/src/lib/account-link-origins.test.ts +72 -0
- package/src/lib/account-link-origins.ts +87 -0
- package/src/lib/account-link-pkce.test.ts +91 -0
- package/src/lib/account-link-pkce.ts +106 -0
- package/src/lib/account-link-provider-registry.test.ts +52 -0
- package/src/lib/account-link-provider-registry.ts +61 -0
- package/src/lib/account-link-throttle.test.ts +178 -0
- package/src/lib/account-link-throttle.ts +130 -0
- package/src/lib/account-link-url.ts +85 -0
- package/src/lib/account-links-emit.test.ts +525 -0
- package/src/lib/account-links-env.test.ts +40 -0
- package/src/lib/account-links-from-env.test.ts +187 -0
- package/src/lib/account-links-from-env.ts +126 -0
- package/src/lib/account-links.ts +1300 -0
- package/src/lib/app-secret.ts +34 -0
- package/src/lib/attachments.ts +81 -0
- package/src/lib/connector-actions.test.ts +13 -4
- package/src/lib/connector-state.account-link.test.ts +114 -0
- package/src/lib/connector-state.ts +48 -3
- package/src/lib/contacts.ts +320 -6
- package/src/lib/domain-status.return-path.test.ts +68 -0
- package/src/lib/domain-status.ts +19 -0
- package/src/lib/email-provider-boot.hogsend.test.ts +48 -0
- package/src/lib/email-provider-boot.test.ts +33 -0
- package/src/lib/email-providers-from-env.hogsend.test.ts +110 -0
- package/src/lib/email-providers-from-env.test.ts +52 -0
- package/src/lib/email-providers-from-env.ts +67 -0
- package/src/lib/email-service-types.ts +11 -0
- package/src/lib/email.ts +17 -0
- package/src/lib/mailer-bounce-idempotency.test.ts +469 -0
- package/src/lib/mailer-rejected.test.ts +229 -0
- package/src/lib/mailer-replied.test.ts +379 -0
- package/src/lib/mailer.ts +359 -24
- package/src/lib/outbound-account-payloads.test.ts +137 -0
- package/src/lib/outbound.ts +126 -0
- package/src/lib/provider-credentials.ts +19 -5
- package/src/lib/sending-domain-guidance.test.ts +99 -0
- package/src/lib/sending-domain-guidance.ts +84 -0
- package/src/lib/tracked-attachments.test.ts +376 -0
- package/src/lib/tracked-idempotency-header.test.ts +437 -0
- package/src/lib/tracked.ts +116 -4
- package/src/lib/tracking-event-names.ts +9 -0
- package/src/lib/webhook-catalog-sync.test.ts +24 -0
- package/src/lib/webhook-signing.ts +25 -1
- package/src/routes/accounts/callback.ts +597 -0
- package/src/routes/accounts/emit.ts +231 -0
- package/src/routes/accounts/import-links.ts +210 -0
- package/src/routes/accounts/index.ts +75 -0
- package/src/routes/accounts/lookup.ts +177 -0
- package/src/routes/accounts/me.ts +215 -0
- package/src/routes/accounts/mint.ts +279 -0
- package/src/routes/accounts/pages.ts +62 -0
- package/src/routes/accounts/resolve.ts +61 -0
- package/src/routes/accounts/serialize.ts +96 -0
- package/src/routes/accounts/shared.ts +107 -0
- package/src/routes/accounts/start.ts +229 -0
- package/src/routes/accounts/unlink.ts +98 -0
- package/src/routes/admin/agent.ts +2 -0
- package/src/routes/admin/api-keys.ts +7 -0
- package/src/routes/admin/contacts.ts +38 -2
- package/src/routes/admin/domain-conflict.test.ts +188 -0
- package/src/routes/admin/domain-return-path.test.ts +274 -0
- package/src/routes/admin/domain.ts +214 -1
- package/src/routes/connectors/index.ts +17 -0
- package/src/routes/contacts/index.ts +8 -0
- package/src/routes/index.ts +75 -0
- package/src/testing-barrel.test.ts +74 -0
- package/src/testing.ts +17 -0
package/src/lib/outbound.ts
CHANGED
|
@@ -211,6 +211,41 @@ export interface OutboundPayloads {
|
|
|
211
211
|
complaintType?: string;
|
|
212
212
|
reason?: string;
|
|
213
213
|
};
|
|
214
|
+
/**
|
|
215
|
+
* A HUMAN REPLIED (PRD 16). The one email event that reports a message
|
|
216
|
+
* coming BACK, so its shape is deliberately NOT `EmailEventPayload`: every
|
|
217
|
+
* send-context field is NULLABLE because a reply that could not be
|
|
218
|
+
* correlated to an `email_sends` row is still delivered here rather than
|
|
219
|
+
* dropped, exactly as the uncorrelated-reply EARS requires.
|
|
220
|
+
*
|
|
221
|
+
* `messageId` is the RECEIVED message's id; `inReplyTo` is the id of OUR
|
|
222
|
+
* send it answers, and it is present only when the relay PROVED that send
|
|
223
|
+
* belongs to this instance. A subscriber may key on `inReplyTo`; it must
|
|
224
|
+
* never key on anything else here, because every other field came out of a
|
|
225
|
+
* message a stranger composed.
|
|
226
|
+
*/
|
|
227
|
+
"email.replied": {
|
|
228
|
+
/** The inbound message's own id — never the id of the send it answers. */
|
|
229
|
+
messageId: string;
|
|
230
|
+
/** OUR send's message id, proven. Null on an uncorrelated reply. */
|
|
231
|
+
inReplyTo: string | null;
|
|
232
|
+
correlated: boolean;
|
|
233
|
+
/** Send context, all null when uncorrelated. */
|
|
234
|
+
emailSendId: string | null;
|
|
235
|
+
templateKey: string | null;
|
|
236
|
+
userId: string | null;
|
|
237
|
+
/** The address WE sent to — not the reply's sender. Null uncorrelated. */
|
|
238
|
+
to: string | null;
|
|
239
|
+
/** The reply's sender, as parsed. Attacker-supplied; display only. */
|
|
240
|
+
from: string | null;
|
|
241
|
+
subject: string | null;
|
|
242
|
+
/** Bounded plain text. Never HTML. */
|
|
243
|
+
text: string | null;
|
|
244
|
+
textTruncated: boolean;
|
|
245
|
+
/** The address the reply arrived at (`hello@reply.acme.com`). */
|
|
246
|
+
recipient: string;
|
|
247
|
+
at: string;
|
|
248
|
+
};
|
|
214
249
|
"sms.sent": {
|
|
215
250
|
smsSendId: string;
|
|
216
251
|
messageId: string;
|
|
@@ -349,6 +384,97 @@ export interface OutboundPayloads {
|
|
|
349
384
|
groupId: string;
|
|
350
385
|
contactId: string;
|
|
351
386
|
};
|
|
387
|
+
/**
|
|
388
|
+
* A third-party platform account (`defineAccountLink`: Steam, Twitch, …) was
|
|
389
|
+
* bound to a contact. Emitted from the intent layer only — the callback
|
|
390
|
+
* handler and the data-plane import — never from the ingest path.
|
|
391
|
+
*
|
|
392
|
+
* FULL CURRENT STATE, never a delta (DECISIONS §5.2). A relink is TWO
|
|
393
|
+
* deliveries — `account.unlinked` for the displaced owner at the LOWER
|
|
394
|
+
* version, then `account.linked` at the higher one — and those retry
|
|
395
|
+
* independently, so they can arrive out of order, duplicated, or a day late.
|
|
396
|
+
* The customer rule that makes all three cases a no-op, verbatim from
|
|
397
|
+
* DECISIONS §5.3: *upsert keyed on `(provider, providerUserId)`; apply only
|
|
398
|
+
* when `incoming.version > stored.version`; otherwise discard.*
|
|
399
|
+
*/
|
|
400
|
+
"account.linked": {
|
|
401
|
+
state: "linked";
|
|
402
|
+
/** The `AccountLinkProvider` meta.id (`"steam"`, `"twitch"`, …). */
|
|
403
|
+
provider: string;
|
|
404
|
+
providerUserId: string;
|
|
405
|
+
contactId: string;
|
|
406
|
+
/** The canonical contact key: `external_id ?? anonymous_id ?? id`. */
|
|
407
|
+
userId: string | null;
|
|
408
|
+
/**
|
|
409
|
+
* The CONTACT's email, never the provider-reported one. A
|
|
410
|
+
* provider-reported address is at most a display property (DECISIONS §6.3
|
|
411
|
+
* / §6.4) and must never become a resolution key downstream.
|
|
412
|
+
*/
|
|
413
|
+
email: string | null;
|
|
414
|
+
/** The provider's display name for the account. */
|
|
415
|
+
username: string | null;
|
|
416
|
+
method: "oauth" | "import";
|
|
417
|
+
/** True when this link displaced a different live owner. */
|
|
418
|
+
relink: boolean;
|
|
419
|
+
/**
|
|
420
|
+
* A decimal STRING, never a JSON number. `linked_accounts.version` is a
|
|
421
|
+
* Postgres `bigint` (DECISIONS §5.1), which exceeds
|
|
422
|
+
* `Number.MAX_SAFE_INTEGER`, so a JSON number silently loses integer
|
|
423
|
+
* fidelity and breaks the `>` guard above in exactly the case that guard
|
|
424
|
+
* exists for. Serialize with `String(row.version)`; compare with
|
|
425
|
+
* `BigInt()` or a numeric column, never `parseInt`.
|
|
426
|
+
*/
|
|
427
|
+
version: string;
|
|
428
|
+
/** ISO 8601. */
|
|
429
|
+
at: string;
|
|
430
|
+
};
|
|
431
|
+
/**
|
|
432
|
+
* A platform account was released from a contact — by the player, by the
|
|
433
|
+
* API/erasure path, or because a relink moved it elsewhere. Emitted from the
|
|
434
|
+
* intent layer only, never from the ingest path.
|
|
435
|
+
*
|
|
436
|
+
* FULL CURRENT STATE, never a delta (DECISIONS §5.2), and it shares the
|
|
437
|
+
* `(provider, providerUserId)` version sequence with `account.linked`, so
|
|
438
|
+
* the same rule applies verbatim from DECISIONS §5.3: *upsert keyed on
|
|
439
|
+
* `(provider, providerUserId)`; apply only when `incoming.version >
|
|
440
|
+
* stored.version`; otherwise discard.*
|
|
441
|
+
*/
|
|
442
|
+
"account.unlinked": {
|
|
443
|
+
state: "unlinked";
|
|
444
|
+
provider: string;
|
|
445
|
+
providerUserId: string;
|
|
446
|
+
contactId: string;
|
|
447
|
+
/** The canonical contact key: `external_id ?? anonymous_id ?? id`. */
|
|
448
|
+
userId: string | null;
|
|
449
|
+
/** The CONTACT's email, never the provider-reported one. */
|
|
450
|
+
email: string | null;
|
|
451
|
+
reason: "player" | "api" | "relinked";
|
|
452
|
+
/**
|
|
453
|
+
* A decimal STRING, never a JSON number — `linked_accounts.version` is a
|
|
454
|
+
* Postgres `bigint` (DECISIONS §5.1) and a JSON number loses fidelity past
|
|
455
|
+
* `Number.MAX_SAFE_INTEGER`. Serialize with `String(row.version)`.
|
|
456
|
+
*/
|
|
457
|
+
version: string;
|
|
458
|
+
/** ISO 8601. */
|
|
459
|
+
at: string;
|
|
460
|
+
};
|
|
461
|
+
/**
|
|
462
|
+
* A link flow ended without binding anything. Deliberately carries NO
|
|
463
|
+
* `version` and NO `state`: nothing mutated, so there is no current state to
|
|
464
|
+
* report and nothing for the `incoming.version > stored.version` guard to
|
|
465
|
+
* compare — a subscriber records this as an attempt, never as ownership.
|
|
466
|
+
*
|
|
467
|
+
* `contactId` is null whenever the flow failed before a trustworthy contact
|
|
468
|
+
* was in hand (a state token that did not verify carries nothing). This
|
|
469
|
+
* event NEVER mints a contact (DECISIONS §8).
|
|
470
|
+
*/
|
|
471
|
+
"account.link_failed": {
|
|
472
|
+
provider: string;
|
|
473
|
+
reason: "denied" | "vetoed" | "exchange_failed" | "state_invalid";
|
|
474
|
+
contactId: string | null;
|
|
475
|
+
/** ISO 8601. */
|
|
476
|
+
at: string;
|
|
477
|
+
};
|
|
352
478
|
}
|
|
353
479
|
|
|
354
480
|
/** Shared payload for the `crm.*` outbound family. */
|
|
@@ -6,7 +6,7 @@ import {
|
|
|
6
6
|
} from "node:crypto";
|
|
7
7
|
import { type Database, providerCredentials } from "@hogsend/db";
|
|
8
8
|
import { and, eq } from "drizzle-orm";
|
|
9
|
-
import {
|
|
9
|
+
import { getAppSecret } from "./app-secret.js";
|
|
10
10
|
|
|
11
11
|
/**
|
|
12
12
|
* Provider-neutral credential storage: encrypted-at-rest OAuth tokens (and,
|
|
@@ -173,6 +173,20 @@ function decryptJson(
|
|
|
173
173
|
return value;
|
|
174
174
|
}
|
|
175
175
|
|
|
176
|
+
/**
|
|
177
|
+
* Seal/unseal for callers OUTSIDE the credential store (today: the
|
|
178
|
+
* account-link store, sealing per-contact token grants into
|
|
179
|
+
* `linked_accounts.tokens`). ONE AES-256-GCM construction in the engine, one
|
|
180
|
+
* place a secret rotation is handled. Same failure posture: an undecryptable
|
|
181
|
+
* blob throws `ProviderCredentialDecryptError` loudly rather than silently
|
|
182
|
+
* degrading.
|
|
183
|
+
*
|
|
184
|
+
* These two aliases are the whole external surface — `encryptJson` /
|
|
185
|
+
* `decryptJson` stay private so there is exactly one name per operation rather
|
|
186
|
+
* than two ways to do the same thing.
|
|
187
|
+
*/
|
|
188
|
+
export { decryptJson as unsealJson, encryptJson as sealJson };
|
|
189
|
+
|
|
176
190
|
function encryptPayload(
|
|
177
191
|
payload: OAuthCredentialPayload,
|
|
178
192
|
secret: string,
|
|
@@ -240,7 +254,7 @@ export async function getProviderCredential(
|
|
|
240
254
|
return {
|
|
241
255
|
providerId: row.providerId,
|
|
242
256
|
kind: row.kind as CredentialKind,
|
|
243
|
-
payload: decryptPayload(row.payload,
|
|
257
|
+
payload: decryptPayload(row.payload, await getAppSecret(), providerId),
|
|
244
258
|
createdAt: row.createdAt,
|
|
245
259
|
updatedAt: row.updatedAt,
|
|
246
260
|
};
|
|
@@ -260,7 +274,7 @@ export async function saveProviderCredential(
|
|
|
260
274
|
},
|
|
261
275
|
): Promise<ProviderCredentialMeta> {
|
|
262
276
|
const kind = opts.kind ?? "oauth";
|
|
263
|
-
const encrypted = encryptPayload(opts.payload,
|
|
277
|
+
const encrypted = encryptPayload(opts.payload, await getAppSecret());
|
|
264
278
|
|
|
265
279
|
const [row] = await db
|
|
266
280
|
.insert(providerCredentials)
|
|
@@ -352,7 +366,7 @@ export async function getDerivedCredential(
|
|
|
352
366
|
|
|
353
367
|
return decryptJson(
|
|
354
368
|
row.payload,
|
|
355
|
-
|
|
369
|
+
await getAppSecret(),
|
|
356
370
|
providerId,
|
|
357
371
|
) as DerivedCredentialPayload;
|
|
358
372
|
}
|
|
@@ -367,7 +381,7 @@ export async function saveDerivedCredential(
|
|
|
367
381
|
providerId: string,
|
|
368
382
|
payload: DerivedCredentialPayload,
|
|
369
383
|
): Promise<void> {
|
|
370
|
-
const encrypted = encryptJson(payload,
|
|
384
|
+
const encrypted = encryptJson(payload, await getAppSecret());
|
|
371
385
|
|
|
372
386
|
await db
|
|
373
387
|
.insert(providerCredentials)
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
|
|
4
|
+
import {
|
|
5
|
+
exampleSendingSubdomain,
|
|
6
|
+
looksLikeRootDomain,
|
|
7
|
+
SENDING_DOMAIN_GUIDANCE,
|
|
8
|
+
} from "./sending-domain-guidance.js";
|
|
9
|
+
|
|
10
|
+
// Same single-label rule apps/cloud/src/lib/sending-domains.ts enforces for
|
|
11
|
+
// return-path labels — a label we RECOMMEND must be one we can publish.
|
|
12
|
+
const DNS_LABEL_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
|
|
13
|
+
|
|
14
|
+
test("looksLikeRootDomain: true for bare two-label domains", () => {
|
|
15
|
+
assert.equal(looksLikeRootDomain("acme.com"), true);
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
test("looksLikeRootDomain: normalizes case", () => {
|
|
19
|
+
assert.equal(looksLikeRootDomain("ACME.COM"), true);
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
test("looksLikeRootDomain: strips a trailing dot", () => {
|
|
23
|
+
assert.equal(looksLikeRootDomain("acme.com."), true);
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
test("looksLikeRootDomain: true for known multi-part public suffixes", () => {
|
|
27
|
+
assert.equal(looksLikeRootDomain("acme.co.uk"), true);
|
|
28
|
+
assert.equal(looksLikeRootDomain("acme.com.au"), true);
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
test("looksLikeRootDomain: false for subdomains", () => {
|
|
32
|
+
assert.equal(looksLikeRootDomain("notifications.acme.com"), false);
|
|
33
|
+
assert.equal(looksLikeRootDomain("mail.acme.co.uk"), false);
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
test("looksLikeRootDomain: false for empty / whitespace / single label", () => {
|
|
37
|
+
assert.equal(looksLikeRootDomain(""), false);
|
|
38
|
+
assert.equal(looksLikeRootDomain(" "), false);
|
|
39
|
+
assert.equal(looksLikeRootDomain("localhost"), false);
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
test("exampleSendingSubdomain prefixes the first recommended label", () => {
|
|
43
|
+
assert.equal(exampleSendingSubdomain("acme.com"), "notifications.acme.com");
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
test("guidance constant is frozen", () => {
|
|
47
|
+
assert.equal(Object.isFrozen(SENDING_DOMAIN_GUIDANCE), true);
|
|
48
|
+
assert.equal(
|
|
49
|
+
Object.isFrozen(SENDING_DOMAIN_GUIDANCE.recommendedLabels),
|
|
50
|
+
true,
|
|
51
|
+
);
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
test("recommended labels are valid single DNS labels", () => {
|
|
55
|
+
assert.ok(SENDING_DOMAIN_GUIDANCE.recommendedLabels.length > 0);
|
|
56
|
+
for (const label of SENDING_DOMAIN_GUIDANCE.recommendedLabels) {
|
|
57
|
+
assert.match(label, DNS_LABEL_RE);
|
|
58
|
+
}
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
// --- Wire proof: the field reaches the EngineDomainStatus snapshot ----------
|
|
62
|
+
// No engine-package test file covers getStatus (the existing coverage lives in
|
|
63
|
+
// apps/api vitest), so the assertion is made here by constructing the service
|
|
64
|
+
// with a domains-less provider — getStatus resolves instantly without any
|
|
65
|
+
// provider call.
|
|
66
|
+
|
|
67
|
+
const { createDomainStatusService } = await import("./domain-status.js");
|
|
68
|
+
|
|
69
|
+
type EngineEnv = Parameters<typeof createDomainStatusService>[0]["env"];
|
|
70
|
+
type EngineLogger = Parameters<typeof createDomainStatusService>[0]["logger"];
|
|
71
|
+
type EngineProvider = Parameters<
|
|
72
|
+
typeof createDomainStatusService
|
|
73
|
+
>[0]["provider"];
|
|
74
|
+
|
|
75
|
+
const noopLogger = {
|
|
76
|
+
error: () => {},
|
|
77
|
+
warn: () => {},
|
|
78
|
+
info: () => {},
|
|
79
|
+
http: () => {},
|
|
80
|
+
debug: () => {},
|
|
81
|
+
} as unknown as EngineLogger;
|
|
82
|
+
|
|
83
|
+
test("getStatus snapshot carries the guidance block", async () => {
|
|
84
|
+
const service = createDomainStatusService({
|
|
85
|
+
provider: { meta: { id: "resend", name: "Resend" } } as EngineProvider,
|
|
86
|
+
env: {
|
|
87
|
+
EMAIL_DOMAIN: "acme.com",
|
|
88
|
+
EMAIL_FROM: undefined,
|
|
89
|
+
RESEND_FROM_EMAIL: undefined,
|
|
90
|
+
HOGSEND_TEST_MODE: "auto",
|
|
91
|
+
HOGSEND_TEST_EMAIL: undefined,
|
|
92
|
+
STUDIO_ADMIN_EMAIL: undefined,
|
|
93
|
+
} as unknown as EngineEnv,
|
|
94
|
+
logger: noopLogger,
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
const snapshot = await service.getStatus();
|
|
98
|
+
assert.equal(snapshot.guidance.title, "Send from a subdomain");
|
|
99
|
+
});
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Sending-subdomain setup guidance — one source of truth for every surface.
|
|
3
|
+
*
|
|
4
|
+
* A customer typing their sending domain will reach for the root
|
|
5
|
+
* (`acme.com`). That works, and it is the wrong default: spam complaints
|
|
6
|
+
* damage the reputation of the domain that sent the mail, and the root also
|
|
7
|
+
* carries password resets, invoices and contracts. The engine recommends a
|
|
8
|
+
* subdomain, states the reason once, and never blocks the root.
|
|
9
|
+
*
|
|
10
|
+
* The shape is structured (not a paragraph blob) so each surface renders it
|
|
11
|
+
* in its own idiom — CLI coloured lines, Studio JSX — with identical words.
|
|
12
|
+
*/
|
|
13
|
+
export interface SendingDomainGuidance {
|
|
14
|
+
/** Short imperative headline. */
|
|
15
|
+
title: string;
|
|
16
|
+
/** The reason, stated once. */
|
|
17
|
+
body: string;
|
|
18
|
+
/** Why it is advice and not a gate. */
|
|
19
|
+
note: string;
|
|
20
|
+
/** Suggested single DNS labels, best first. */
|
|
21
|
+
recommendedLabels: readonly string[];
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** The approved copy. Frozen — surfaces render it, never mutate it. */
|
|
25
|
+
export const SENDING_DOMAIN_GUIDANCE: SendingDomainGuidance = Object.freeze({
|
|
26
|
+
title: "Send from a subdomain",
|
|
27
|
+
body: "Use notifications.acme.com rather than acme.com. Spam complaints damage the reputation of the domain that sent the mail, and your root domain also carries your password resets, invoices and contracts. A subdomain keeps that damage in one place.",
|
|
28
|
+
note: "Root domains work. This is a recommendation, not a requirement.",
|
|
29
|
+
recommendedLabels: Object.freeze(["notifications", "mail", "updates"]),
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
/** `acme.com` -> `notifications.acme.com`. Uses the first recommended label. */
|
|
33
|
+
export function exampleSendingSubdomain(domain: string): string {
|
|
34
|
+
return `${SENDING_DOMAIN_GUIDANCE.recommendedLabels[0]}.${domain}`;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Known multi-part public suffixes, so `acme.co.uk` counts as root-like.
|
|
39
|
+
*
|
|
40
|
+
* This is a short embedded list, NOT a Public Suffix List implementation.
|
|
41
|
+
* The failure mode is deliberately silence: an unlisted multi-part suffix
|
|
42
|
+
* (say `acme.something.gov.xx`) reads as a subdomain and produces no warning.
|
|
43
|
+
* A false NEGATIVE is a missed hint; a false POSITIVE nags someone who
|
|
44
|
+
* already typed `notifications.acme.com` and did the right thing.
|
|
45
|
+
*/
|
|
46
|
+
const MULTI_PART_SUFFIXES = new Set([
|
|
47
|
+
"co.uk",
|
|
48
|
+
"org.uk",
|
|
49
|
+
"me.uk",
|
|
50
|
+
"com.au",
|
|
51
|
+
"net.au",
|
|
52
|
+
"org.au",
|
|
53
|
+
"co.nz",
|
|
54
|
+
"co.za",
|
|
55
|
+
"co.jp",
|
|
56
|
+
"com.br",
|
|
57
|
+
"com.mx",
|
|
58
|
+
"co.in",
|
|
59
|
+
"com.sg",
|
|
60
|
+
]);
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Whether `domain` looks like a ROOT domain (`acme.com`, `acme.co.uk`) rather
|
|
64
|
+
* than a subdomain (`notifications.acme.com`) — the case where the subdomain
|
|
65
|
+
* recommendation is worth surfacing. Callers warn ONLY when this is true, so
|
|
66
|
+
* someone who already typed a subdomain is never nagged.
|
|
67
|
+
*
|
|
68
|
+
* Rule: exactly two labels, OR three labels whose last two form a known
|
|
69
|
+
* multi-part public suffix (see {@link MULTI_PART_SUFFIXES} for the honest
|
|
70
|
+
* limits of that list). Input is normalized (trim, lowercase, trailing dot
|
|
71
|
+
* stripped); empty / whitespace / single-label input returns `false` —
|
|
72
|
+
* nothing sensible to say about it.
|
|
73
|
+
*/
|
|
74
|
+
export function looksLikeRootDomain(domain: string): boolean {
|
|
75
|
+
const normalized = domain.trim().toLowerCase().replace(/\.$/, "");
|
|
76
|
+
if (!normalized) return false;
|
|
77
|
+
|
|
78
|
+
const labels = normalized.split(".");
|
|
79
|
+
if (labels.length === 2) return true;
|
|
80
|
+
if (labels.length === 3) {
|
|
81
|
+
return MULTI_PART_SUFFIXES.has(labels.slice(-2).join("."));
|
|
82
|
+
}
|
|
83
|
+
return false;
|
|
84
|
+
}
|