@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.
- package/package.json +12 -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 +37 -0
- package/src/index.ts +87 -1
- 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/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/outbound-account-payloads.test.ts +137 -0
- package/src/lib/outbound.ts +91 -0
- package/src/lib/provider-credentials.ts +19 -5
- package/src/lib/webhook-catalog-sync.test.ts +24 -0
- package/src/lib/webhook-signing.ts +18 -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/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
|
@@ -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 {
|
|
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)
|
|
@@ -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
|
|
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",
|