@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
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Lazy access to `env.BETTER_AUTH_SECRET`, the engine's one master secret
|
|
3
|
+
* (AES-256-GCM key material for sealed link tokens and stored provider
|
|
4
|
+
* credentials).
|
|
5
|
+
*
|
|
6
|
+
* WHY THIS MODULE EXISTS: `../env.js` calls `createEnv` at MODULE SCOPE, so a
|
|
7
|
+
* static `import { env }` anywhere makes that file's whole import graph
|
|
8
|
+
* unloadable without a full, valid environment. `lib/account-links.ts` and
|
|
9
|
+
* `lib/provider-credentials.ts` are both reachable from `src/testing.ts` — the
|
|
10
|
+
* `@hogsend/engine/testing` entry point, which `@hogsend/testing` imports from
|
|
11
|
+
* a consumer app that has NO environment at all (the scaffold's packed-consumer
|
|
12
|
+
* smoke runs it under plain `tsx` with every var stripped). A static env import
|
|
13
|
+
* on that path turns "import a journey test helper" into "Invalid environment
|
|
14
|
+
* variables".
|
|
15
|
+
*
|
|
16
|
+
* Neither module reads the secret at module scope — only inside functions that
|
|
17
|
+
* are already `async` — so resolving it lazily costs nothing and validates
|
|
18
|
+
* EXACTLY the same contract: this loads the real `env.js`, it does not re-read
|
|
19
|
+
* or re-validate `process.env` itself. In a running API/worker `env.js` is
|
|
20
|
+
* already in the module cache (the container imports it at boot, so a bad
|
|
21
|
+
* environment still fails fast at startup); here the `await` just hands back
|
|
22
|
+
* the cached module.
|
|
23
|
+
*
|
|
24
|
+
* The promise is memoised, so the module is loaded — and, on a bad
|
|
25
|
+
* environment, throws — exactly once.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
let secret: Promise<string> | undefined;
|
|
29
|
+
|
|
30
|
+
/** The validated `BETTER_AUTH_SECRET`, loading `env.js` on first use. */
|
|
31
|
+
export function getAppSecret(): Promise<string> {
|
|
32
|
+
secret ??= import("../env.js").then((m) => m.env.BETTER_AUTH_SECRET);
|
|
33
|
+
return secret;
|
|
34
|
+
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import type { EmailAttachment, EmailProvider } from "@hogsend/core";
|
|
2
|
+
import { assertValidAttachments, attachmentByteLength } from "@hogsend/core";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Thrown when a send carries attachments but the resolved provider does not
|
|
6
|
+
* declare `capabilities.attachments`. A named class (mirroring
|
|
7
|
+
* `TestModeNoRedirectError`) so callers can branch on it without
|
|
8
|
+
* string-matching the message; the message itself names the provider id AND
|
|
9
|
+
* the capability so an operator reading a log can act on it directly.
|
|
10
|
+
*/
|
|
11
|
+
export class AttachmentsUnsupportedError extends Error {
|
|
12
|
+
readonly code = "attachments_unsupported";
|
|
13
|
+
constructor(readonly providerId: string) {
|
|
14
|
+
super(
|
|
15
|
+
`Email provider "${providerId}" does not declare capabilities.attachments — ` +
|
|
16
|
+
`refusing to send a message without its files. Switch to a provider that ` +
|
|
17
|
+
`carries attachments, or drop the attachments from this send.`,
|
|
18
|
+
);
|
|
19
|
+
this.name = "AttachmentsUnsupportedError";
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* The engine-side attachment gate, run BEFORE any other send work (no DB row,
|
|
25
|
+
* no render, no provider call happens first). Two checks, in order:
|
|
26
|
+
*
|
|
27
|
+
* 1. `assertValidAttachments` — shape/size/count validation. The relay
|
|
28
|
+
* validates too, and that is deliberate defence in depth rather than
|
|
29
|
+
* duplication: a Resend or Postmark send never passes through the relay at
|
|
30
|
+
* all, so for those providers THIS is the only gate before the wire.
|
|
31
|
+
*
|
|
32
|
+
* 2. The capability gate — throw unless the provider DECLARES
|
|
33
|
+
* `capabilities.attachments === true`. The quiet alternative (send the
|
|
34
|
+
* message, drop the files) is genuinely tempting and genuinely wrong: a
|
|
35
|
+
* receipt that arrives without its invoice looks *delivered* from every
|
|
36
|
+
* dashboard, from `email_sends`, and from the provider's own logs — nobody
|
|
37
|
+
* discovers it until the customer does. Absence of the flag is NOT consent
|
|
38
|
+
* (same rule as `consumesIdempotencyKey`): an absent or `false` flag means
|
|
39
|
+
* the provider cannot carry the files, so the send must fail loudly here,
|
|
40
|
+
* before anything is written or dispatched.
|
|
41
|
+
*/
|
|
42
|
+
export function assertAttachmentsSendable(
|
|
43
|
+
provider: EmailProvider,
|
|
44
|
+
attachments: EmailAttachment[],
|
|
45
|
+
): void {
|
|
46
|
+
assertValidAttachments(attachments);
|
|
47
|
+
if (provider.capabilities?.attachments !== true) {
|
|
48
|
+
throw new AttachmentsUnsupportedError(provider.meta?.id ?? "resend");
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* One recorded metadata entry per attachment on the `email_sends` row:
|
|
54
|
+
* filename, raw byte size, and content type when declared.
|
|
55
|
+
*/
|
|
56
|
+
export interface AttachmentSendMetadata {
|
|
57
|
+
filename: string;
|
|
58
|
+
sizeBytes: number;
|
|
59
|
+
contentType?: string;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* What `email_sends.metadata.attachments` records: that the message HAD
|
|
64
|
+
* attachments — their filenames, raw sizes, and content types. NEVER the
|
|
65
|
+
* content itself. Storing customer invoices indefinitely is a data-protection
|
|
66
|
+
* decision nobody has made, and quietly making it here by persisting bytes
|
|
67
|
+
* would be the wrong default. Size comes from `attachmentByteLength` (raw
|
|
68
|
+
* bytes, decoded for `{ base64 }` content) so the recorded number matches the
|
|
69
|
+
* one the size cap enforces.
|
|
70
|
+
*/
|
|
71
|
+
export function attachmentSendMetadata(
|
|
72
|
+
attachments: EmailAttachment[],
|
|
73
|
+
): AttachmentSendMetadata[] {
|
|
74
|
+
return attachments.map((attachment) => ({
|
|
75
|
+
filename: attachment.filename,
|
|
76
|
+
sizeBytes: attachmentByteLength(attachment),
|
|
77
|
+
...(attachment.contentType !== undefined
|
|
78
|
+
? { contentType: attachment.contentType }
|
|
79
|
+
: {}),
|
|
80
|
+
}));
|
|
81
|
+
}
|
|
@@ -23,10 +23,19 @@ import {
|
|
|
23
23
|
ContactSourceRegistry,
|
|
24
24
|
setContactSourceRegistry,
|
|
25
25
|
} from "../sources/registry.js";
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
26
|
+
|
|
27
|
+
// connector-actions' import chain reaches env.ts (validates required env vars
|
|
28
|
+
// at import time — via contacts.ts → the account-link store, PRD 04) — stub
|
|
29
|
+
// the required vars BEFORE the dynamic import, exactly as bucket-emit.test.ts
|
|
30
|
+
// does. Nothing is ever contacted: the boundary/registry seams intercept
|
|
31
|
+
// everything, and the DATABASE_URL points at a port nothing listens on.
|
|
32
|
+
process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
|
|
33
|
+
process.env.BETTER_AUTH_SECRET ??= "test-secret";
|
|
34
|
+
process.env.HATCHET_CLIENT_TOKEN ??=
|
|
35
|
+
"eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
|
|
36
|
+
const { checkActionAudience, sendConnectorAction } = await import(
|
|
37
|
+
"./connector-actions.js"
|
|
38
|
+
);
|
|
30
39
|
|
|
31
40
|
test("a scoped connector override requires registration validation before capture", async () => {
|
|
32
41
|
let captures = 0;
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import {
|
|
4
|
+
type ConnectorStateIntent,
|
|
5
|
+
signConnectorState,
|
|
6
|
+
verifyConnectorState,
|
|
7
|
+
} from "./connector-state.js";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* PRD 07 T1 — the `account_link` purpose on the ONE state token format.
|
|
11
|
+
*
|
|
12
|
+
* There is deliberately no second token: `BETTER_AUTH_SECRET` signs every state
|
|
13
|
+
* in the process, so a second format would be a second thing to keep hardened.
|
|
14
|
+
* What IS new is `providerId`, which is why the cross-surface tests below (and
|
|
15
|
+
* `apps/api/src/__tests__/connectors-oauth-state-purpose.test.ts`) exist.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
const SECRET = "test-secret-for-account-link-state-minimum-32-characters";
|
|
19
|
+
|
|
20
|
+
const WARM: ConnectorStateIntent = {
|
|
21
|
+
purpose: "account_link",
|
|
22
|
+
providerId: "steam",
|
|
23
|
+
contactId: "11111111-2222-3333-4444-555555555555",
|
|
24
|
+
returnTo: "https://play.example.com/settings",
|
|
25
|
+
nonce: "nonce-warm",
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
const COLD: ConnectorStateIntent = {
|
|
29
|
+
purpose: "account_link",
|
|
30
|
+
providerId: "twitch",
|
|
31
|
+
anonymousId: "anon-abc",
|
|
32
|
+
nonce: "nonce-cold",
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
test("signs and verifies an account_link intent round-trip", () => {
|
|
36
|
+
for (const intent of [WARM, COLD]) {
|
|
37
|
+
const result = verifyConnectorState(
|
|
38
|
+
signConnectorState(intent, SECRET, 900),
|
|
39
|
+
SECRET,
|
|
40
|
+
);
|
|
41
|
+
assert.equal(result.valid, true);
|
|
42
|
+
assert.deepEqual(result.intent, intent);
|
|
43
|
+
// The connector surface's binding field is absent, not empty-string.
|
|
44
|
+
assert.equal(result.intent?.connectorId, undefined);
|
|
45
|
+
}
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
test("a tampered payload fails with bad_signature", () => {
|
|
49
|
+
const token = signConnectorState(WARM, SECRET, 900);
|
|
50
|
+
const [payloadB64, sig] = token.split(".");
|
|
51
|
+
assert.ok(payloadB64 && sig);
|
|
52
|
+
const payload = JSON.parse(
|
|
53
|
+
Buffer.from(payloadB64, "base64url").toString("utf8"),
|
|
54
|
+
) as Record<string, unknown>;
|
|
55
|
+
// The exact attack the signature exists to stop: re-point the sealed
|
|
56
|
+
// contact at someone else's row and keep the old signature.
|
|
57
|
+
payload.contactId = "99999999-9999-9999-9999-999999999999";
|
|
58
|
+
const forged = `${Buffer.from(JSON.stringify(payload)).toString("base64url")}.${sig}`;
|
|
59
|
+
|
|
60
|
+
const result = verifyConnectorState(forged, SECRET);
|
|
61
|
+
assert.equal(result.valid, false);
|
|
62
|
+
assert.equal(result.reason, "bad_signature");
|
|
63
|
+
assert.equal(result.intent, undefined);
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
test("an expired account_link state fails with expired", () => {
|
|
67
|
+
const token = signConnectorState(WARM, SECRET, -1);
|
|
68
|
+
const result = verifyConnectorState(token, SECRET);
|
|
69
|
+
assert.equal(result.valid, false);
|
|
70
|
+
assert.equal(result.reason, "expired");
|
|
71
|
+
assert.equal(result.intent, undefined);
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
test("the existing install/member_link round-trips are unchanged", () => {
|
|
75
|
+
const install: ConnectorStateIntent = {
|
|
76
|
+
purpose: "install",
|
|
77
|
+
connectorId: "discord",
|
|
78
|
+
nonce: "nonce-install",
|
|
79
|
+
};
|
|
80
|
+
const memberLink: ConnectorStateIntent = {
|
|
81
|
+
purpose: "member_link",
|
|
82
|
+
connectorId: "discord",
|
|
83
|
+
contactId: "contact-123",
|
|
84
|
+
email: "alice@example.com",
|
|
85
|
+
nonce: "nonce-member",
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
for (const intent of [install, memberLink]) {
|
|
89
|
+
const result = verifyConnectorState(
|
|
90
|
+
signConnectorState(intent, SECRET, 600),
|
|
91
|
+
SECRET,
|
|
92
|
+
);
|
|
93
|
+
assert.equal(result.valid, true);
|
|
94
|
+
assert.deepEqual(result.intent, intent);
|
|
95
|
+
// Neither connector purpose ever carries the account-link fields.
|
|
96
|
+
assert.equal(result.intent?.providerId, undefined);
|
|
97
|
+
assert.equal(result.intent?.anonymousId, undefined);
|
|
98
|
+
assert.equal(result.intent?.returnTo, undefined);
|
|
99
|
+
}
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
test("an account_link state carries no connectorId, so the connector callback's own check rejects it", () => {
|
|
103
|
+
// `routes/connectors/index.ts` compares `intent.connectorId !== id`, and
|
|
104
|
+
// `undefined !== "steam"` is true. This pins the INCIDENTAL half of the
|
|
105
|
+
// defence; the EXPLICIT purpose allowlist is pinned separately in
|
|
106
|
+
// `apps/api/src/__tests__/connectors-oauth-state-purpose.test.ts` so the two
|
|
107
|
+
// guards are never aliased onto one test.
|
|
108
|
+
const result = verifyConnectorState(
|
|
109
|
+
signConnectorState(WARM, SECRET, 900),
|
|
110
|
+
SECRET,
|
|
111
|
+
);
|
|
112
|
+
assert.equal(result.valid, true);
|
|
113
|
+
assert.notEqual(result.intent?.connectorId, "steam");
|
|
114
|
+
});
|
|
@@ -13,6 +13,14 @@ import { safeEqual } from "../webhook-sources/verify.js";
|
|
|
13
13
|
* link was issued for, so the callback attaches the platform identity to THAT
|
|
14
14
|
* contact (never to whatever email the platform happens to report — the
|
|
15
15
|
* grafting/account-takeover vector).
|
|
16
|
+
* - `purpose: "account_link"` — binds ONE account-link attempt
|
|
17
|
+
* (`/v1/accounts/:provider/start` → `/callback`, PRD 07) to the provider it
|
|
18
|
+
* was minted for (`providerId`) and to the contact side it may attach to:
|
|
19
|
+
* either a sealed `contactId` (the WARM binding, authoritative — the
|
|
20
|
+
* provider-reported email is NEVER a resolution key) or an `anonymousId`
|
|
21
|
+
* (the COLD binding, which may attach only to an anonymous-only contact,
|
|
22
|
+
* DECISIONS §6.10). It also carries the already-allowlist-checked
|
|
23
|
+
* `returnTo`, re-checked at redirect time.
|
|
16
24
|
*
|
|
17
25
|
* The token is `base64url(JSON(payload)).base64url(HMAC-SHA256(payloadB64))`,
|
|
18
26
|
* signed with the engine's `BETTER_AUTH_SECRET`. The same hardened constant-time
|
|
@@ -25,12 +33,49 @@ import { safeEqual } from "../webhook-sources/verify.js";
|
|
|
25
33
|
* it, but the same token works until expiry. The mint TTL is the replay window.
|
|
26
34
|
*/
|
|
27
35
|
export interface ConnectorStateIntent {
|
|
28
|
-
purpose: "install" | "member_link";
|
|
29
|
-
|
|
30
|
-
|
|
36
|
+
purpose: "install" | "member_link" | "account_link";
|
|
37
|
+
/**
|
|
38
|
+
* Connector flows only (`install` / `member_link`). OPTIONAL now that
|
|
39
|
+
* `account_link` exists — an account-link state binds `providerId` instead.
|
|
40
|
+
*/
|
|
41
|
+
connectorId?: string;
|
|
42
|
+
/**
|
|
43
|
+
* `account_link` only — the `AccountLinkProvider` `meta.id` this state was
|
|
44
|
+
* minted for.
|
|
45
|
+
*
|
|
46
|
+
* A NEW field, deliberately NOT a reuse of {@link connectorId}: one secret
|
|
47
|
+
* signs every state in the process, so a state minted for one surface is
|
|
48
|
+
* signature-valid on the other, and a future connector id colliding with an
|
|
49
|
+
* account-link provider id (both `"discord"`, say) would make the two
|
|
50
|
+
* indistinguishable. Two fields cannot be confused. The connector callback's
|
|
51
|
+
* `intent.connectorId !== id` check already rejects an account-link state
|
|
52
|
+
* incidentally (`undefined !== id`), and it also states the rule explicitly
|
|
53
|
+
* with a purpose allowlist.
|
|
54
|
+
*/
|
|
55
|
+
providerId?: string;
|
|
56
|
+
/**
|
|
57
|
+
* `member_link`, and `account_link`'s WARM binding — the bound contact id.
|
|
58
|
+
* AUTHORITATIVE: the callback attaches to THIS contact and never to whatever
|
|
59
|
+
* email the platform reports (DECISIONS §6.3).
|
|
60
|
+
*/
|
|
31
61
|
contactId?: string;
|
|
32
62
|
/** Member-link only — the bound contact email (authoritative resolution key). */
|
|
33
63
|
email?: string;
|
|
64
|
+
/**
|
|
65
|
+
* `account_link` COLD binding only — the browser anonymous key the link
|
|
66
|
+
* attaches to. It is browser-readable by design, so a cold link may attach
|
|
67
|
+
* ONLY to an anonymous-only contact and may never displace a live owner
|
|
68
|
+
* (DECISIONS §6.10). Exactly one of {@link contactId} / `anonymousId` is set
|
|
69
|
+
* on an account-link state.
|
|
70
|
+
*/
|
|
71
|
+
anonymousId?: string;
|
|
72
|
+
/**
|
|
73
|
+
* `account_link` only — where to send the player after a completed link.
|
|
74
|
+
* Allowlist-checked at MINT time AND re-checked at redirect time, because
|
|
75
|
+
* the allowlist can change between the two (and a signed state outlives a
|
|
76
|
+
* config edit).
|
|
77
|
+
*/
|
|
78
|
+
returnTo?: string;
|
|
34
79
|
/**
|
|
35
80
|
* High-entropy per-mint value so two states are never byte-identical AND so
|
|
36
81
|
* the callback can burn it for single-use replay protection (see header).
|