@hogsend/engine 0.64.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 (68) hide show
  1. package/package.json +12 -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 +37 -0
  16. package/src/index.ts +87 -1
  17. package/src/lib/account-link-emit.ts +126 -0
  18. package/src/lib/account-link-events.ts +180 -0
  19. package/src/lib/account-link-hooks.test.ts +158 -0
  20. package/src/lib/account-link-hooks.ts +73 -0
  21. package/src/lib/account-link-ingest.ts +364 -0
  22. package/src/lib/account-link-nonce.test.ts +52 -0
  23. package/src/lib/account-link-nonce.ts +57 -0
  24. package/src/lib/account-link-origins.test.ts +72 -0
  25. package/src/lib/account-link-origins.ts +87 -0
  26. package/src/lib/account-link-pkce.test.ts +91 -0
  27. package/src/lib/account-link-pkce.ts +106 -0
  28. package/src/lib/account-link-provider-registry.test.ts +52 -0
  29. package/src/lib/account-link-provider-registry.ts +61 -0
  30. package/src/lib/account-link-throttle.test.ts +178 -0
  31. package/src/lib/account-link-throttle.ts +130 -0
  32. package/src/lib/account-link-url.ts +85 -0
  33. package/src/lib/account-links-emit.test.ts +525 -0
  34. package/src/lib/account-links-env.test.ts +40 -0
  35. package/src/lib/account-links-from-env.test.ts +187 -0
  36. package/src/lib/account-links-from-env.ts +126 -0
  37. package/src/lib/account-links.ts +1300 -0
  38. package/src/lib/app-secret.ts +34 -0
  39. package/src/lib/connector-actions.test.ts +13 -4
  40. package/src/lib/connector-state.account-link.test.ts +114 -0
  41. package/src/lib/connector-state.ts +48 -3
  42. package/src/lib/contacts.ts +320 -6
  43. package/src/lib/outbound-account-payloads.test.ts +137 -0
  44. package/src/lib/outbound.ts +91 -0
  45. package/src/lib/provider-credentials.ts +19 -5
  46. package/src/lib/webhook-catalog-sync.test.ts +24 -0
  47. package/src/lib/webhook-signing.ts +18 -1
  48. package/src/routes/accounts/callback.ts +597 -0
  49. package/src/routes/accounts/emit.ts +231 -0
  50. package/src/routes/accounts/import-links.ts +210 -0
  51. package/src/routes/accounts/index.ts +75 -0
  52. package/src/routes/accounts/lookup.ts +177 -0
  53. package/src/routes/accounts/me.ts +215 -0
  54. package/src/routes/accounts/mint.ts +279 -0
  55. package/src/routes/accounts/pages.ts +62 -0
  56. package/src/routes/accounts/resolve.ts +61 -0
  57. package/src/routes/accounts/serialize.ts +96 -0
  58. package/src/routes/accounts/shared.ts +107 -0
  59. package/src/routes/accounts/start.ts +229 -0
  60. package/src/routes/accounts/unlink.ts +98 -0
  61. package/src/routes/admin/agent.ts +2 -0
  62. package/src/routes/admin/api-keys.ts +7 -0
  63. package/src/routes/admin/contacts.ts +38 -2
  64. package/src/routes/connectors/index.ts +17 -0
  65. package/src/routes/contacts/index.ts +8 -0
  66. package/src/routes/index.ts +75 -0
  67. package/src/testing-barrel.test.ts +74 -0
  68. package/src/testing.ts +17 -0
@@ -384,6 +384,97 @@ export interface OutboundPayloads {
384
384
  groupId: string;
385
385
  contactId: string;
386
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
+ };
387
478
  }
388
479
 
389
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)
@@ -95,6 +95,30 @@ test("AC 4: contact.refined is present in ALL THREE hand-synced catalogs", () =>
95
95
  );
96
96
  });
97
97
 
98
+ test("AC: the three account.* events are present in ALL THREE hand-synced catalogs", () => {
99
+ const engine = WEBHOOK_EVENT_TYPES as readonly string[];
100
+ const cli = readCliCatalog();
101
+ const client = readClientCatalog();
102
+ for (const event of [
103
+ "account.linked",
104
+ "account.unlinked",
105
+ "account.link_failed",
106
+ ]) {
107
+ assert.ok(
108
+ engine.includes(event),
109
+ `packages/engine/src/lib/webhook-signing.ts is missing ${event}`,
110
+ );
111
+ assert.ok(
112
+ cli.includes(event),
113
+ `packages/cli/src/commands/webhooks.ts is missing ${event}`,
114
+ );
115
+ assert.ok(
116
+ client.includes(event),
117
+ `packages/client/src/types.ts is missing ${event}`,
118
+ );
119
+ }
120
+ });
121
+
98
122
  test("AC 4: the CLI's vendored catalog is the engine catalog, entry for entry", () => {
99
123
  assertSameSet(
100
124
  readCliCatalog(),
@@ -25,7 +25,7 @@ import { Webhook } from "svix";
25
25
  */
26
26
 
27
27
  /**
28
- * The 31-event catalog — the SINGLE source of truth (schema, routes, client,
28
+ * The 35-event catalog — the SINGLE source of truth (schema, routes, client,
29
29
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
30
30
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
31
31
  *
@@ -49,6 +49,16 @@ import { Webhook } from "svix";
49
49
  * visitor reported back from the destination (opt-in `hs_ref` +
50
50
  * POST /v1/t/arrive) with identity evidence.
51
51
  *
52
+ * The `account.*` family reports a player's third-party platform account
53
+ * (`defineAccountLink`: Steam, Twitch, …) being bound to or released from a
54
+ * contact. `account.linked` and `account.unlinked` are the two STATE events —
55
+ * each carries the FULL current state including `{ state, version }`, never a
56
+ * delta, so a subscriber upserts on `(provider, providerUserId)` and applies
57
+ * only when `incoming.version > stored.version`. `account.link_failed` reports
58
+ * a flow that ended without mutating anything, so it carries no version and
59
+ * never mints a contact. Like `group.*`, all three are emitted from the
60
+ * intent-layer link/unlink call sites ONLY — never from the ingest path.
61
+ *
52
62
  * `impact.digest` is the weekly facts-only impact rollup (shipped journey
53
63
  * versions/labels + holdout-lift threshold crossings). It is the one
54
64
  * SELF-REFERENTIAL event: the digest cron derives its watermark from its
@@ -101,6 +111,13 @@ export const WEBHOOK_EVENT_TYPES = [
101
111
  "group.identified",
102
112
  "group.member_added",
103
113
  "group.member_removed",
114
+ // Third-party platform account links (`defineAccountLink`). Emitted from the
115
+ // intent layer ONLY (the link/unlink call sites), never the ingest path.
116
+ // The two STATE events carry full current state + a monotonic `version`;
117
+ // `account.link_failed` mutated nothing, so it carries neither.
118
+ "account.linked",
119
+ "account.unlinked",
120
+ "account.link_failed",
104
121
  // Weekly impact digest (impact experiments D5). Self-referential: the
105
122
  // cron watermarks off its own delivery rows.
106
123
  "impact.digest",