@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.
Files changed (92) hide show
  1. package/package.json +13 -12
  2. package/src/account-links/__fixtures__/fake-fetch.test.ts +57 -0
  3. package/src/account-links/__fixtures__/fake-fetch.ts +114 -0
  4. package/src/account-links/__fixtures__/steam.json +21 -0
  5. package/src/account-links/__fixtures__/twitch.json +22 -0
  6. package/src/account-links/index.ts +8 -0
  7. package/src/account-links/steam.test.ts +243 -0
  8. package/src/account-links/steam.ts +48 -0
  9. package/src/account-links/twitch.test.ts +157 -0
  10. package/src/account-links/twitch.ts +99 -0
  11. package/src/container.account-links.env.test.ts +65 -0
  12. package/src/container.account-links.halfenv.test.ts +48 -0
  13. package/src/container.account-links.test.ts +185 -0
  14. package/src/container.ts +120 -0
  15. package/src/env.ts +60 -0
  16. package/src/index.ts +104 -1
  17. package/src/journeys/journey-boundary.ts +8 -0
  18. package/src/lib/account-link-emit.ts +126 -0
  19. package/src/lib/account-link-events.ts +180 -0
  20. package/src/lib/account-link-hooks.test.ts +158 -0
  21. package/src/lib/account-link-hooks.ts +73 -0
  22. package/src/lib/account-link-ingest.ts +364 -0
  23. package/src/lib/account-link-nonce.test.ts +52 -0
  24. package/src/lib/account-link-nonce.ts +57 -0
  25. package/src/lib/account-link-origins.test.ts +72 -0
  26. package/src/lib/account-link-origins.ts +87 -0
  27. package/src/lib/account-link-pkce.test.ts +91 -0
  28. package/src/lib/account-link-pkce.ts +106 -0
  29. package/src/lib/account-link-provider-registry.test.ts +52 -0
  30. package/src/lib/account-link-provider-registry.ts +61 -0
  31. package/src/lib/account-link-throttle.test.ts +178 -0
  32. package/src/lib/account-link-throttle.ts +130 -0
  33. package/src/lib/account-link-url.ts +85 -0
  34. package/src/lib/account-links-emit.test.ts +525 -0
  35. package/src/lib/account-links-env.test.ts +40 -0
  36. package/src/lib/account-links-from-env.test.ts +187 -0
  37. package/src/lib/account-links-from-env.ts +126 -0
  38. package/src/lib/account-links.ts +1300 -0
  39. package/src/lib/app-secret.ts +34 -0
  40. package/src/lib/attachments.ts +81 -0
  41. package/src/lib/connector-actions.test.ts +13 -4
  42. package/src/lib/connector-state.account-link.test.ts +114 -0
  43. package/src/lib/connector-state.ts +48 -3
  44. package/src/lib/contacts.ts +320 -6
  45. package/src/lib/domain-status.return-path.test.ts +68 -0
  46. package/src/lib/domain-status.ts +19 -0
  47. package/src/lib/email-provider-boot.hogsend.test.ts +48 -0
  48. package/src/lib/email-provider-boot.test.ts +33 -0
  49. package/src/lib/email-providers-from-env.hogsend.test.ts +110 -0
  50. package/src/lib/email-providers-from-env.test.ts +52 -0
  51. package/src/lib/email-providers-from-env.ts +67 -0
  52. package/src/lib/email-service-types.ts +11 -0
  53. package/src/lib/email.ts +17 -0
  54. package/src/lib/mailer-bounce-idempotency.test.ts +469 -0
  55. package/src/lib/mailer-rejected.test.ts +229 -0
  56. package/src/lib/mailer-replied.test.ts +379 -0
  57. package/src/lib/mailer.ts +359 -24
  58. package/src/lib/outbound-account-payloads.test.ts +137 -0
  59. package/src/lib/outbound.ts +126 -0
  60. package/src/lib/provider-credentials.ts +19 -5
  61. package/src/lib/sending-domain-guidance.test.ts +99 -0
  62. package/src/lib/sending-domain-guidance.ts +84 -0
  63. package/src/lib/tracked-attachments.test.ts +376 -0
  64. package/src/lib/tracked-idempotency-header.test.ts +437 -0
  65. package/src/lib/tracked.ts +116 -4
  66. package/src/lib/tracking-event-names.ts +9 -0
  67. package/src/lib/webhook-catalog-sync.test.ts +24 -0
  68. package/src/lib/webhook-signing.ts +25 -1
  69. package/src/routes/accounts/callback.ts +597 -0
  70. package/src/routes/accounts/emit.ts +231 -0
  71. package/src/routes/accounts/import-links.ts +210 -0
  72. package/src/routes/accounts/index.ts +75 -0
  73. package/src/routes/accounts/lookup.ts +177 -0
  74. package/src/routes/accounts/me.ts +215 -0
  75. package/src/routes/accounts/mint.ts +279 -0
  76. package/src/routes/accounts/pages.ts +62 -0
  77. package/src/routes/accounts/resolve.ts +61 -0
  78. package/src/routes/accounts/serialize.ts +96 -0
  79. package/src/routes/accounts/shared.ts +107 -0
  80. package/src/routes/accounts/start.ts +229 -0
  81. package/src/routes/accounts/unlink.ts +98 -0
  82. package/src/routes/admin/agent.ts +2 -0
  83. package/src/routes/admin/api-keys.ts +7 -0
  84. package/src/routes/admin/contacts.ts +38 -2
  85. package/src/routes/admin/domain-conflict.test.ts +188 -0
  86. package/src/routes/admin/domain-return-path.test.ts +274 -0
  87. package/src/routes/admin/domain.ts +214 -1
  88. package/src/routes/connectors/index.ts +17 -0
  89. package/src/routes/contacts/index.ts +8 -0
  90. package/src/routes/index.ts +75 -0
  91. package/src/testing-barrel.test.ts +74 -0
  92. package/src/testing.ts +17 -0
@@ -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 { env } from "../env.js";
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, env.BETTER_AUTH_SECRET, providerId),
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, env.BETTER_AUTH_SECRET);
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
- env.BETTER_AUTH_SECRET,
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, env.BETTER_AUTH_SECRET);
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
+ }