@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
@@ -0,0 +1,178 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import {
4
+ type AccountLinkThrottleRedis,
5
+ checkAccountLinkThrottle,
6
+ } from "./account-link-throttle.js";
7
+
8
+ /**
9
+ * PRD 07 T3. The fake redis is the whole point: this throttle is FAIL-CLOSED
10
+ * (DECISIONS §6.8), which is the opposite of the connector callback's
11
+ * degrade-to-TTL posture, so the "no redis" arm must be exercised directly.
12
+ */
13
+ function fakeRedis(opts: { throwOnIncr?: boolean } = {}): {
14
+ redis: AccountLinkThrottleRedis;
15
+ counts: Map<string, number>;
16
+ expires: Array<{ key: string; seconds: number }>;
17
+ } {
18
+ const counts = new Map<string, number>();
19
+ const expires: Array<{ key: string; seconds: number }> = [];
20
+ return {
21
+ counts,
22
+ expires,
23
+ redis: {
24
+ async incr(key) {
25
+ if (opts.throwOnIncr) throw new Error("connection lost");
26
+ const next = (counts.get(key) ?? 0) + 1;
27
+ counts.set(key, next);
28
+ return next;
29
+ },
30
+ async expire(key, seconds) {
31
+ expires.push({ key, seconds });
32
+ return 1;
33
+ },
34
+ },
35
+ };
36
+ }
37
+
38
+ test("allows under the cap", async () => {
39
+ const { redis } = fakeRedis();
40
+ for (let i = 0; i < 20; i++) {
41
+ const result = await checkAccountLinkThrottle({
42
+ surface: "start",
43
+ ip: "203.0.113.7",
44
+ redis,
45
+ });
46
+ assert.deepEqual(result, { ok: true }, `attempt ${i + 1} should pass`);
47
+ }
48
+ });
49
+
50
+ test("rejects over the cap with rate_limited", async () => {
51
+ const { redis } = fakeRedis();
52
+ for (let i = 0; i < 20; i++) {
53
+ await checkAccountLinkThrottle({
54
+ surface: "callback",
55
+ ip: "203.0.113.8",
56
+ redis,
57
+ });
58
+ }
59
+ const result = await checkAccountLinkThrottle({
60
+ surface: "callback",
61
+ ip: "203.0.113.8",
62
+ redis,
63
+ });
64
+ assert.deepEqual(result, { ok: false, reason: "rate_limited" });
65
+ });
66
+
67
+ test("rejects with redis_unavailable when redis is null", async () => {
68
+ // FAIL-CLOSED. A replayed account link can MOVE a platform account between
69
+ // contacts, so a cache miss must never wave one through.
70
+ const result = await checkAccountLinkThrottle({
71
+ surface: "start",
72
+ ip: "203.0.113.9",
73
+ redis: null,
74
+ });
75
+ assert.deepEqual(result, { ok: false, reason: "redis_unavailable" });
76
+ });
77
+
78
+ test("rejects with redis_unavailable when redis throws", async () => {
79
+ const { redis } = fakeRedis({ throwOnIncr: true });
80
+ const result = await checkAccountLinkThrottle({
81
+ surface: "start",
82
+ ip: "203.0.113.10",
83
+ redis,
84
+ });
85
+ assert.deepEqual(result, { ok: false, reason: "redis_unavailable" });
86
+ });
87
+
88
+ test("sets the TTL exactly once, on the first increment", async () => {
89
+ const { redis, expires } = fakeRedis();
90
+ for (let i = 0; i < 5; i++) {
91
+ await checkAccountLinkThrottle({
92
+ surface: "start",
93
+ ip: "203.0.113.11",
94
+ redis,
95
+ });
96
+ }
97
+ assert.deepEqual(expires, [
98
+ { key: "hogsend:al:throttle:start:203.0.113.11", seconds: 900 },
99
+ ]);
100
+ });
101
+
102
+ test("the warm path adds a per-contact budget on its own key", async () => {
103
+ const { redis, counts } = fakeRedis();
104
+ await checkAccountLinkThrottle({
105
+ surface: "start",
106
+ ip: "203.0.113.12",
107
+ contactId: "c-1",
108
+ redis,
109
+ });
110
+ assert.equal(counts.get("hogsend:al:throttle:start:203.0.113.12"), 1);
111
+ assert.equal(counts.get("hogsend:al:throttle:contact:c-1"), 1);
112
+ });
113
+
114
+ test("a per-contact budget over the cap rejects even from a fresh IP", async () => {
115
+ const { redis } = fakeRedis();
116
+ for (let i = 0; i < 20; i++) {
117
+ await checkAccountLinkThrottle({
118
+ surface: "start",
119
+ ip: `198.51.100.${i}`,
120
+ contactId: "c-hot",
121
+ redis,
122
+ });
123
+ }
124
+ const result = await checkAccountLinkThrottle({
125
+ surface: "start",
126
+ ip: "198.51.100.200",
127
+ contactId: "c-hot",
128
+ redis,
129
+ });
130
+ assert.deepEqual(result, { ok: false, reason: "rate_limited" });
131
+ });
132
+
133
+ test("a contact-only call bumps the contact budget and no IP budget", async () => {
134
+ // `/start` calls this shape for the WARM leg, after the binding is known —
135
+ // re-passing the IP would double-count it against its own budget.
136
+ const { redis, counts } = fakeRedis();
137
+ const result = await checkAccountLinkThrottle({
138
+ surface: "start",
139
+ contactId: "c-2",
140
+ redis,
141
+ });
142
+ assert.deepEqual(result, { ok: true });
143
+ assert.deepEqual([...counts.keys()], ["hogsend:al:throttle:contact:c-2"]);
144
+ });
145
+
146
+ test("start and callback hold separate budgets", async () => {
147
+ const { redis, counts } = fakeRedis();
148
+ await checkAccountLinkThrottle({ surface: "start", ip: "1.2.3.4", redis });
149
+ await checkAccountLinkThrottle({ surface: "callback", ip: "1.2.3.4", redis });
150
+ assert.equal(counts.get("hogsend:al:throttle:start:1.2.3.4"), 1);
151
+ assert.equal(counts.get("hogsend:al:throttle:cb:1.2.3.4"), 1);
152
+ });
153
+
154
+ test("config overrides the window and the cap", async () => {
155
+ const { redis, expires } = fakeRedis();
156
+ const config = { windowSeconds: 60, max: 1 };
157
+ assert.deepEqual(
158
+ await checkAccountLinkThrottle({
159
+ surface: "start",
160
+ ip: "5.6.7.8",
161
+ config,
162
+ redis,
163
+ }),
164
+ { ok: true },
165
+ );
166
+ assert.deepEqual(
167
+ await checkAccountLinkThrottle({
168
+ surface: "start",
169
+ ip: "5.6.7.8",
170
+ config,
171
+ redis,
172
+ }),
173
+ { ok: false, reason: "rate_limited" },
174
+ );
175
+ assert.deepEqual(expires, [
176
+ { key: "hogsend:al:throttle:start:5.6.7.8", seconds: 60 },
177
+ ]);
178
+ });
@@ -0,0 +1,130 @@
1
+ import { getRedisIfConnected } from "./redis.js";
2
+
3
+ /**
4
+ * The public account-link surfaces (`/v1/accounts/:provider/start` and
5
+ * `/callback`) are UNAUTHENTICATED by construction — a browser redirect target
6
+ * carries no `Authorization` header — so they are throttled per IP, and the
7
+ * warm mint is additionally throttled per contact.
8
+ *
9
+ * FAIL-CLOSED (DECISIONS §6.8), which is a DELIBERATE divergence from the
10
+ * connector callback next door: that one degrades to TTL-only validity when
11
+ * Redis is absent on the stated principle that it will "never block a callback
12
+ * on a cache miss" (`routes/connectors/index.ts:134-136`). The threat is not
13
+ * the same. A replayed connector install re-captures a guild id; a replayed
14
+ * account-link callback can MOVE a platform account between contacts
15
+ * (DECISIONS §6.1). PKCE verifier custody also lives in Redis, so for the
16
+ * OAuth2 providers Redis is structurally required regardless. Do not "fix" this
17
+ * into the connector posture.
18
+ *
19
+ * Modelled on `cold-connect/throttle.ts` — the same fixed-window `INCR` + set
20
+ * the TTL on the FIRST increment idiom.
21
+ */
22
+
23
+ /**
24
+ * The slice of ioredis this module uses. Narrowed so a test can inject a fake
25
+ * (and so `null` — the fail-closed arm — is expressible), the same seam
26
+ * `lib/leader-lease.ts` uses for its `redis` argument.
27
+ */
28
+ export interface AccountLinkThrottleRedis {
29
+ incr(key: string): Promise<number>;
30
+ expire(key: string, seconds: number): Promise<unknown>;
31
+ }
32
+
33
+ export type ThrottleResult =
34
+ | { ok: true }
35
+ | { ok: false; reason: "rate_limited" | "redis_unavailable" };
36
+
37
+ const DEFAULT_WINDOW_SECONDS = 900;
38
+ const DEFAULT_MAX = 20;
39
+
40
+ /** The key namespaces, one per budget. `cb` keeps the key short and readable. */
41
+ const SURFACE_KEY = { start: "start", callback: "cb" } as const;
42
+
43
+ interface AccountLinkThrottleBase {
44
+ surface: "start" | "callback";
45
+ config?: { windowSeconds?: number; max?: number };
46
+ /**
47
+ * TEST SEAM (and the fail-closed arm). Defaults to
48
+ * {@link getRedisIfConnected}, NOT `getRedis()`: the account-link routes
49
+ * refuse to serve at all without a connected Redis, so this must never be the
50
+ * thing that lazily opens a connection and papers over that.
51
+ */
52
+ redis?: AccountLinkThrottleRedis | null;
53
+ }
54
+
55
+ /**
56
+ * At least ONE budget must be named, enforced by the union rather than by a
57
+ * runtime check — a call that names no budget would silently allow everything.
58
+ *
59
+ * `/start` calls this TWICE and that is deliberate: once on the IP alone,
60
+ * BEFORE anything is minted (the order of operations puts the throttle ahead of
61
+ * the binding resolution), and once on the sealed `contactId` alone once the
62
+ * WARM binding is known. One call cannot do both, because the contact is not
63
+ * known at the point the IP budget has to bite, and re-passing the IP on the
64
+ * second call would double-count every warm request against its own budget.
65
+ */
66
+ export type AccountLinkThrottleArgs = AccountLinkThrottleBase &
67
+ (
68
+ | {
69
+ /** Best-effort client IP; `"unknown"` shares ONE bounded bucket, never bypasses. */
70
+ ip: string;
71
+ contactId?: string;
72
+ }
73
+ | {
74
+ ip?: undefined;
75
+ /** WARM only — the sealed contact gets its own budget across IPs. */
76
+ contactId: string;
77
+ }
78
+ );
79
+
80
+ /**
81
+ * One fixed-window counter. `INCR`, then set the TTL on the FIRST increment
82
+ * only so the window slides forward rather than being extended by traffic. A
83
+ * missing client throws so the caller fails CLOSED.
84
+ */
85
+ async function bump(
86
+ redis: AccountLinkThrottleRedis | null | undefined,
87
+ key: string,
88
+ windowSeconds: number,
89
+ ): Promise<number> {
90
+ if (!redis) throw new Error("redis_unavailable");
91
+ const count = await redis.incr(key);
92
+ if (count === 1) await redis.expire(key, windowSeconds);
93
+ return count;
94
+ }
95
+
96
+ /**
97
+ * Bump every budget this call owns and reject when ANY is over its cap. Both
98
+ * budgets are bumped even when the first is already over: a fixed-window
99
+ * counter that stops counting under attack is a counter that reopens early.
100
+ */
101
+ export async function checkAccountLinkThrottle(
102
+ args: AccountLinkThrottleArgs,
103
+ ): Promise<ThrottleResult> {
104
+ const windowSeconds = args.config?.windowSeconds ?? DEFAULT_WINDOW_SECONDS;
105
+ const max = args.config?.max ?? DEFAULT_MAX;
106
+ const redis = args.redis === undefined ? getRedisIfConnected() : args.redis;
107
+
108
+ const keys = [
109
+ ...(args.ip
110
+ ? [`hogsend:al:throttle:${SURFACE_KEY[args.surface]}:${args.ip}`]
111
+ : []),
112
+ ...(args.contactId
113
+ ? [`hogsend:al:throttle:contact:${args.contactId}`]
114
+ : []),
115
+ ];
116
+
117
+ try {
118
+ const counts = await Promise.all(
119
+ keys.map((key) => bump(redis, key, windowSeconds)),
120
+ );
121
+ if (counts.some((count) => count > max)) {
122
+ return { ok: false, reason: "rate_limited" };
123
+ }
124
+ return { ok: true };
125
+ } catch {
126
+ // Any Redis fault — absent client, connection loss, command error — is a
127
+ // refusal, never a bypass.
128
+ return { ok: false, reason: "redis_unavailable" };
129
+ }
130
+ }
@@ -0,0 +1,85 @@
1
+ import { randomBytes } from "node:crypto";
2
+ import { env } from "../env.js";
3
+ import { isAllowedReturnTo } from "./account-link-origins.js";
4
+ import { signConnectorState } from "./connector-state.js";
5
+
6
+ /**
7
+ * Mint a WARM account-link URL for a KNOWN contact — the server-side half of
8
+ * DECISIONS §2's naming (`mintAccountLinkUrl`, never `mintLinkUrl` beside
9
+ * `mintLink`). PRD 09's `POST /v1/accounts/link-url` returns exactly this
10
+ * value, and the embed SDK derives its `postMessage` `expectedOrigin` from it.
11
+ *
12
+ * **It returns an ENGINE-origin URL** (DECISIONS §15.2):
13
+ *
14
+ * <API_PUBLIC_URL>/v1/accounts/<provider>/start?t=<signed account_link state>
15
+ *
16
+ * The provider's authorize URL is only ever a 302 target from `/start`, NEVER a
17
+ * value handed to a caller. This is not tidiness: the embed compares the
18
+ * `postMessage` origin against `new URL(url).origin`, so returning
19
+ * `https://steamcommunity.com/...` would make it silently drop every success
20
+ * message and time out while the link had committed server-side — and a
21
+ * fake-`Window` test cannot see that.
22
+ */
23
+ export class AccountLinkReturnToError extends Error {
24
+ constructor(returnTo: string) {
25
+ super(
26
+ `returnTo "${returnTo}" is not on the account-link origin allowlist — ` +
27
+ "add its origin to ACCOUNT_LINK_ALLOWED_ORIGINS (or " +
28
+ "accountLinks.allowedOrigins)",
29
+ );
30
+ this.name = "AccountLinkReturnToError";
31
+ }
32
+ }
33
+
34
+ export interface MintAccountLinkUrlArgs {
35
+ /** The `AccountLinkProvider` `meta.id`. Sealed into the state as `providerId`. */
36
+ provider: string;
37
+ /**
38
+ * The contact this link attaches to, AUTHORITATIVELY. Sealed into the state,
39
+ * so the callback binds here and never to the email the provider reports
40
+ * (DECISIONS §6.3). Minting is an identity assertion, which is why PRD 09
41
+ * gates the route on a server-minted userToken and never on a `pk_` key.
42
+ */
43
+ contactId: string;
44
+ /** Where to send the player afterwards. Checked HERE and again at redirect. */
45
+ returnTo?: string;
46
+ /** The container's parsed allowlist. Required to accept a `returnTo` at all. */
47
+ allowedOrigins?: readonly string[];
48
+ /** Defaults to `env.API_PUBLIC_URL`. */
49
+ apiPublicUrl?: string;
50
+ /** Defaults to `env.ACCOUNT_LINK_STATE_TTL_SECONDS`. */
51
+ ttlSeconds?: number;
52
+ }
53
+
54
+ export function mintAccountLinkUrl(args: MintAccountLinkUrlArgs): string {
55
+ if (
56
+ args.returnTo !== undefined &&
57
+ !isAllowedReturnTo(args.returnTo, args.allowedOrigins ?? [])
58
+ ) {
59
+ // Refuse at MINT time as well as at redirect time. An unchecked value here
60
+ // would be signed by us, and a signed open redirect is worse than an
61
+ // unsigned one — it looks verified.
62
+ throw new AccountLinkReturnToError(args.returnTo);
63
+ }
64
+
65
+ const state = signConnectorState(
66
+ {
67
+ purpose: "account_link",
68
+ providerId: args.provider,
69
+ contactId: args.contactId,
70
+ ...(args.returnTo ? { returnTo: args.returnTo } : {}),
71
+ nonce: randomBytes(16).toString("base64url"),
72
+ },
73
+ env.BETTER_AUTH_SECRET,
74
+ args.ttlSeconds ?? env.ACCOUNT_LINK_STATE_TTL_SECONDS,
75
+ );
76
+
77
+ // Trailing slash stripped for the same reason the SMS webhook route strips
78
+ // it: it is the one operator-controlled degree of freedom in API_PUBLIC_URL.
79
+ const base = (args.apiPublicUrl ?? env.API_PUBLIC_URL).replace(/\/+$/, "");
80
+ const url = new URL(
81
+ `${base}/v1/accounts/${encodeURIComponent(args.provider)}/start`,
82
+ );
83
+ url.searchParams.set("t", state);
84
+ return url.toString();
85
+ }