Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
+433
@@ -0,0 +1,433 @@
|
||||
import { createHash, timingSafeEqual } from "node:crypto";
|
||||
|
||||
export const PORTAL_SETUP_MAIL_SOURCE = "portal_setup_invite" as const;
|
||||
export const PORTAL_SETUP_TOKEN_PLACEHOLDER = "__HIVEGRID_PORTAL_SETUP_CAPABILITY__" as const;
|
||||
export const PORTAL_SETUP_SECRET_REDACTED_MARKER = "secretBodyRedacted" as const;
|
||||
export const PORTAL_SETUP_DELIVERY_STATUS_KEY = "portalSetupDeliveryStatus" as const;
|
||||
export const PORTAL_SETUP_DELIVERY_STARTED = "delivery_started" as const;
|
||||
export const PORTAL_SETUP_PROVIDER_ACCEPTED = "provider_accepted" as const;
|
||||
export const PORTAL_SETUP_ROTATION_REQUIRED = "rotation_required" as const;
|
||||
|
||||
export type PortalSetupMailMetadata = {
|
||||
source: typeof PORTAL_SETUP_MAIL_SOURCE;
|
||||
invitationSource: string;
|
||||
portalId: string;
|
||||
portalUserId: string;
|
||||
portalTokenId: string;
|
||||
setupTokenHash: string;
|
||||
expiresAt: string;
|
||||
mailContentHash: string;
|
||||
encryptedCapability?: string;
|
||||
outboxEventId?: string;
|
||||
dispatchKey?: string;
|
||||
};
|
||||
|
||||
export type PortalSetupCapabilityPlaintextInput = {
|
||||
tenantId: string;
|
||||
rawToken: string;
|
||||
metadata: Omit<PortalSetupMailMetadata, "source" | "encryptedCapability" | "outboxEventId" | "dispatchKey">;
|
||||
};
|
||||
|
||||
export type PortalSetupMailOutboxBinding = {
|
||||
outboxEventId: string;
|
||||
dispatchKey: string;
|
||||
};
|
||||
|
||||
export function hashPortalSetupMailContent(input: {
|
||||
recipient: string;
|
||||
subject: string;
|
||||
text: string;
|
||||
html: string;
|
||||
}): string {
|
||||
const recipient = normalizeRecipient(input.recipient);
|
||||
const subject = normalizeMailText(input.subject);
|
||||
const text = normalizeMailText(input.text);
|
||||
const html = normalizeMailText(input.html);
|
||||
if (
|
||||
!recipient ||
|
||||
!subject ||
|
||||
!text.includes(PORTAL_SETUP_TOKEN_PLACEHOLDER) ||
|
||||
!html.includes(PORTAL_SETUP_TOKEN_PLACEHOLDER)
|
||||
) {
|
||||
throw new Error("Portal setup mail content is incomplete.");
|
||||
}
|
||||
return sha256(JSON.stringify({ version: 1, recipient, subject, text, html }));
|
||||
}
|
||||
|
||||
export function buildPortalSetupCapabilityPlaintext(input: PortalSetupCapabilityPlaintextInput): string {
|
||||
const tenantId = normalizeIdentifier(input.tenantId, "tenantId");
|
||||
const metadata = normalizeMetadata({ source: PORTAL_SETUP_MAIL_SOURCE, ...input.metadata });
|
||||
if (!isRawToken(input.rawToken) || !hashesEqual(sha256(input.rawToken), metadata.setupTokenHash)) {
|
||||
throw new Error("Portal setup capability does not match its token hash.");
|
||||
}
|
||||
return JSON.stringify({
|
||||
version: 1,
|
||||
tenantId,
|
||||
portalId: metadata.portalId,
|
||||
portalUserId: metadata.portalUserId,
|
||||
portalTokenId: metadata.portalTokenId,
|
||||
purpose: "setup",
|
||||
expiresAt: metadata.expiresAt,
|
||||
setupTokenHash: metadata.setupTokenHash,
|
||||
mailContentHash: metadata.mailContentHash,
|
||||
rawToken: input.rawToken,
|
||||
});
|
||||
}
|
||||
|
||||
export function readPortalSetupCapabilityPlaintext(
|
||||
plaintext: string,
|
||||
expected: { tenantId: string; metadata: PortalSetupMailMetadata },
|
||||
): string {
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(plaintext);
|
||||
} catch {
|
||||
throw new Error("Portal setup capability envelope is invalid.");
|
||||
}
|
||||
const record = asRecord(parsed);
|
||||
const metadata = normalizeMetadata(expected.metadata);
|
||||
if (
|
||||
!record ||
|
||||
!hasExactKeys(record, [
|
||||
"version",
|
||||
"tenantId",
|
||||
"portalId",
|
||||
"portalUserId",
|
||||
"portalTokenId",
|
||||
"purpose",
|
||||
"expiresAt",
|
||||
"setupTokenHash",
|
||||
"mailContentHash",
|
||||
"rawToken",
|
||||
]) ||
|
||||
record.version !== 1 ||
|
||||
record.purpose !== "setup" ||
|
||||
record.tenantId !== normalizeIdentifier(expected.tenantId, "tenantId") ||
|
||||
record.portalId !== metadata.portalId ||
|
||||
record.portalUserId !== metadata.portalUserId ||
|
||||
record.portalTokenId !== metadata.portalTokenId ||
|
||||
record.expiresAt !== metadata.expiresAt ||
|
||||
record.setupTokenHash !== metadata.setupTokenHash ||
|
||||
record.mailContentHash !== metadata.mailContentHash ||
|
||||
typeof record.rawToken !== "string" ||
|
||||
!isRawToken(record.rawToken) ||
|
||||
!hashesEqual(sha256(record.rawToken), metadata.setupTokenHash)
|
||||
) {
|
||||
throw new Error("Portal setup capability envelope does not match its mail identity.");
|
||||
}
|
||||
return record.rawToken;
|
||||
}
|
||||
|
||||
export function readPortalSetupMailMetadata(payload: unknown): PortalSetupMailMetadata | null {
|
||||
const record = asRecord(payload);
|
||||
const metadata = asRecord(record?.metadata);
|
||||
if (metadata?.source !== PORTAL_SETUP_MAIL_SOURCE) return null;
|
||||
try {
|
||||
return normalizeMetadata(metadata);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Binds the encrypted capability to the durable outbox identity before it is
|
||||
* materialized for the provider queue. The dispatch key is derived from the
|
||||
* persisted token id so an envelope cannot be paired with another event.
|
||||
*/
|
||||
export function bindEncryptedPortalSetupMailToOutbox(
|
||||
payload: unknown,
|
||||
binding: PortalSetupMailOutboxBinding,
|
||||
): Record<string, unknown> {
|
||||
if (!hasValidEncryptedPortalSetupMailContent(payload)) {
|
||||
throw new Error("Portal setup encrypted mail contract is invalid.");
|
||||
}
|
||||
const record = payload as Record<string, unknown>;
|
||||
const metadata = readPortalSetupMailMetadata(payload)!;
|
||||
const outboxEventId = normalizeIdentifier(binding.outboxEventId, "outboxEventId");
|
||||
const dispatchKey = normalizeIdentifier(binding.dispatchKey, "dispatchKey", 256);
|
||||
if (
|
||||
dispatchKey !== portalSetupDispatchKey(metadata.portalTokenId) ||
|
||||
(metadata.outboxEventId !== undefined && metadata.outboxEventId !== outboxEventId) ||
|
||||
(metadata.dispatchKey !== undefined && metadata.dispatchKey !== dispatchKey)
|
||||
) {
|
||||
throw new Error("Portal setup mail outbox binding is invalid.");
|
||||
}
|
||||
return {
|
||||
...record,
|
||||
metadata: {
|
||||
...(record.metadata as Record<string, unknown>),
|
||||
outboxEventId,
|
||||
dispatchKey,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export function isPortalSetupMailIntent(payload: unknown): boolean {
|
||||
return asRecord(asRecord(payload)?.metadata)?.source === PORTAL_SETUP_MAIL_SOURCE;
|
||||
}
|
||||
|
||||
export function hasValidEncryptedPortalSetupMailContent(payload: unknown): boolean {
|
||||
const record = asRecord(payload);
|
||||
const metadata = readPortalSetupMailMetadata(payload);
|
||||
if (!record || !metadata || !metadata.encryptedCapability) return false;
|
||||
if (!hasExactPayloadShape(record, "encrypted") || !hasExactMetadataShape(asRecord(record.metadata), "encrypted")) return false;
|
||||
if (!hasCommonMailIdentity(record, metadata) || !hasValidOptionalOutboxBinding(metadata)) return false;
|
||||
if (typeof record.text !== "string" || typeof record.html !== "string") return false;
|
||||
if (!record.text.includes(PORTAL_SETUP_TOKEN_PLACEHOLDER) || !record.html.includes(PORTAL_SETUP_TOKEN_PLACEHOLDER)) return false;
|
||||
try {
|
||||
const actual = hashPortalSetupMailContent({
|
||||
recipient: (record.to as string[])[0]!,
|
||||
subject: record.subject as string,
|
||||
text: record.text,
|
||||
html: record.html,
|
||||
});
|
||||
return hashesEqual(actual, metadata.mailContentHash);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export function materializePortalSetupMailContent(payload: unknown, rawToken: string): Record<string, unknown> {
|
||||
if (!hasValidEncryptedPortalSetupMailContent(payload)) {
|
||||
throw new Error("Portal setup encrypted mail contract is invalid.");
|
||||
}
|
||||
const record = payload as Record<string, unknown>;
|
||||
const metadata = readPortalSetupMailMetadata(payload)!;
|
||||
if (!isRawToken(rawToken) || !hashesEqual(sha256(rawToken), metadata.setupTokenHash)) {
|
||||
throw new Error("Portal setup decrypted capability does not match its token hash.");
|
||||
}
|
||||
const { encryptedCapability: _encryptedCapability, ...safeMetadata } = metadata;
|
||||
return {
|
||||
...record,
|
||||
text: (record.text as string).replaceAll(PORTAL_SETUP_TOKEN_PLACEHOLDER, rawToken),
|
||||
html: (record.html as string).replaceAll(PORTAL_SETUP_TOKEN_PLACEHOLDER, rawToken),
|
||||
metadata: safeMetadata,
|
||||
};
|
||||
}
|
||||
|
||||
export function hasValidMaterializedPortalSetupMailContent(payload: unknown): boolean {
|
||||
const record = asRecord(payload);
|
||||
const metadata = readPortalSetupMailMetadata(payload);
|
||||
if (
|
||||
!record ||
|
||||
!metadata ||
|
||||
metadata.encryptedCapability !== undefined ||
|
||||
!hasExactPayloadShape(record, "materialized") ||
|
||||
!hasExactMetadataShape(asRecord(record.metadata), "materialized") ||
|
||||
!hasCommonMailIdentity(record, metadata) ||
|
||||
!hasRequiredOutboxBinding(metadata)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
if (typeof record.text !== "string" || typeof record.html !== "string") return false;
|
||||
const rawToken = findPortalSetupRawToken(record.text, record.html, metadata.setupTokenHash);
|
||||
if (!rawToken) return false;
|
||||
try {
|
||||
const actual = hashPortalSetupMailContent({
|
||||
recipient: (record.to as string[])[0]!,
|
||||
subject: record.subject as string,
|
||||
text: record.text.replaceAll(rawToken, PORTAL_SETUP_TOKEN_PLACEHOLDER),
|
||||
html: record.html.replaceAll(rawToken, PORTAL_SETUP_TOKEN_PLACEHOLDER),
|
||||
});
|
||||
return hashesEqual(actual, metadata.mailContentHash);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export function hasValidRedactedPortalSetupMailContent(payload: unknown): boolean {
|
||||
const record = asRecord(payload);
|
||||
const metadata = readPortalSetupMailMetadata(payload);
|
||||
if (
|
||||
!record ||
|
||||
!metadata ||
|
||||
!hasExactPayloadShape(record, "redacted") ||
|
||||
!hasExactMetadataShape(asRecord(record.metadata), "redacted") ||
|
||||
!hasCommonMailIdentity(record, metadata) ||
|
||||
!hasValidOptionalOutboxBinding(metadata)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
return (
|
||||
metadata.encryptedCapability === undefined &&
|
||||
asRecord(record.metadata)?.[PORTAL_SETUP_SECRET_REDACTED_MARKER] === true &&
|
||||
!("text" in record) &&
|
||||
!("html" in record) &&
|
||||
!("templateData" in record) &&
|
||||
!("attachments" in record)
|
||||
);
|
||||
}
|
||||
|
||||
export function findPortalSetupRawToken(text: string, html: string, setupTokenHash: string): string | null {
|
||||
if (!isSha256(setupTokenHash)) return null;
|
||||
const candidates = new Set(
|
||||
`${text}\n${html}`.match(/(?:\/setup\/)([A-Za-z0-9_-]{32,512})/gu)?.map((match) => match.slice("/setup/".length)) ?? [],
|
||||
);
|
||||
const matching = [...candidates].filter((candidate) => hashesEqual(sha256(candidate), setupTokenHash));
|
||||
return matching.length === 1 ? matching[0]! : null;
|
||||
}
|
||||
|
||||
export function portalSetupMailHashesEqual(actual: string, expected: string): boolean {
|
||||
return hashesEqual(actual, expected);
|
||||
}
|
||||
|
||||
function normalizeMetadata(value: Record<string, unknown> | PortalSetupMailMetadata): PortalSetupMailMetadata {
|
||||
if (value.source !== PORTAL_SETUP_MAIL_SOURCE) throw new Error("Portal setup mail source is invalid.");
|
||||
const invitationSource = normalizeIdentifier(value.invitationSource, "invitationSource", 80);
|
||||
const portalId = normalizeIdentifier(value.portalId, "portalId");
|
||||
const portalUserId = normalizeIdentifier(value.portalUserId, "portalUserId");
|
||||
const portalTokenId = normalizeIdentifier(value.portalTokenId, "portalTokenId");
|
||||
if (!isSha256(value.setupTokenHash) || !isSha256(value.mailContentHash)) {
|
||||
throw new Error("Portal setup mail digest is invalid.");
|
||||
}
|
||||
const expiresAt = normalizeDate(value.expiresAt);
|
||||
const encryptedCapability =
|
||||
value.encryptedCapability === undefined
|
||||
? undefined
|
||||
: normalizeIdentifier(value.encryptedCapability, "encryptedCapability", 16_384);
|
||||
const outboxEventId = value.outboxEventId === undefined ? undefined : normalizeIdentifier(value.outboxEventId, "outboxEventId");
|
||||
const dispatchKey = value.dispatchKey === undefined ? undefined : normalizeIdentifier(value.dispatchKey, "dispatchKey", 256);
|
||||
return {
|
||||
source: PORTAL_SETUP_MAIL_SOURCE,
|
||||
invitationSource,
|
||||
portalId,
|
||||
portalUserId,
|
||||
portalTokenId,
|
||||
setupTokenHash: value.setupTokenHash,
|
||||
expiresAt,
|
||||
mailContentHash: value.mailContentHash,
|
||||
...(encryptedCapability ? { encryptedCapability } : {}),
|
||||
...(outboxEventId ? { outboxEventId } : {}),
|
||||
...(dispatchKey ? { dispatchKey } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
function hasCommonMailIdentity(record: Record<string, unknown>, metadata: PortalSetupMailMetadata): boolean {
|
||||
return (
|
||||
typeof record.tenantId === "string" &&
|
||||
record.tenantId.trim().length > 0 &&
|
||||
Array.isArray(record.to) &&
|
||||
record.to.length === 1 &&
|
||||
typeof record.to[0] === "string" &&
|
||||
record.to[0].includes("@") &&
|
||||
typeof record.subject === "string" &&
|
||||
record.subject.trim().length > 0 &&
|
||||
metadata.source === PORTAL_SETUP_MAIL_SOURCE
|
||||
);
|
||||
}
|
||||
|
||||
function hasExactPayloadShape(record: Record<string, unknown>, state: "encrypted" | "materialized" | "redacted"): boolean {
|
||||
const allowed = new Set([
|
||||
"kind",
|
||||
"tenantId",
|
||||
"to",
|
||||
"subject",
|
||||
"priorityOverride",
|
||||
"metadata",
|
||||
...(state === "redacted" ? [] : ["text", "html"]),
|
||||
]);
|
||||
return (
|
||||
Object.keys(record).every((key) => allowed.has(key)) &&
|
||||
(record.kind === undefined || record.kind === "mail.transactional") &&
|
||||
typeof record.tenantId === "string" &&
|
||||
record.tenantId.trim().length > 0 &&
|
||||
(record.priorityOverride === undefined || record.priorityOverride === "critical") &&
|
||||
(state === "redacted" ? !("text" in record) && !("html" in record) : typeof record.text === "string" && typeof record.html === "string")
|
||||
);
|
||||
}
|
||||
|
||||
function hasExactMetadataShape(
|
||||
metadata: Record<string, unknown> | null,
|
||||
state: "encrypted" | "materialized" | "redacted",
|
||||
): boolean {
|
||||
if (!metadata) return false;
|
||||
const allowed = new Set([
|
||||
"source",
|
||||
"invitationSource",
|
||||
"portalId",
|
||||
"portalUserId",
|
||||
"portalTokenId",
|
||||
"setupTokenHash",
|
||||
"expiresAt",
|
||||
"mailContentHash",
|
||||
"outboxEventId",
|
||||
"dispatchKey",
|
||||
...(state === "encrypted" ? ["encryptedCapability"] : []),
|
||||
...(state === "redacted" ? [PORTAL_SETUP_SECRET_REDACTED_MARKER, PORTAL_SETUP_DELIVERY_STATUS_KEY] : []),
|
||||
]);
|
||||
const status = metadata[PORTAL_SETUP_DELIVERY_STATUS_KEY];
|
||||
return (
|
||||
Object.keys(metadata).every((key) => allowed.has(key)) &&
|
||||
(state !== "encrypted" || typeof metadata.encryptedCapability === "string") &&
|
||||
(state !== "redacted" ||
|
||||
(metadata[PORTAL_SETUP_SECRET_REDACTED_MARKER] === true &&
|
||||
(status === undefined ||
|
||||
status === PORTAL_SETUP_DELIVERY_STARTED ||
|
||||
status === PORTAL_SETUP_PROVIDER_ACCEPTED ||
|
||||
status === PORTAL_SETUP_ROTATION_REQUIRED)))
|
||||
);
|
||||
}
|
||||
|
||||
function hasValidOptionalOutboxBinding(metadata: PortalSetupMailMetadata): boolean {
|
||||
if (metadata.outboxEventId === undefined && metadata.dispatchKey === undefined) return true;
|
||||
return hasRequiredOutboxBinding(metadata);
|
||||
}
|
||||
|
||||
function hasRequiredOutboxBinding(metadata: PortalSetupMailMetadata): boolean {
|
||||
return Boolean(
|
||||
metadata.outboxEventId && metadata.dispatchKey && metadata.dispatchKey === portalSetupDispatchKey(metadata.portalTokenId),
|
||||
);
|
||||
}
|
||||
|
||||
function portalSetupDispatchKey(portalTokenId: string): string {
|
||||
return `portal-setup:${portalTokenId}`;
|
||||
}
|
||||
|
||||
function hasExactKeys(record: Record<string, unknown>, expected: readonly string[]): boolean {
|
||||
return Object.keys(record).length === expected.length && Object.keys(record).every((key) => expected.includes(key));
|
||||
}
|
||||
|
||||
function normalizeRecipient(value: string): string {
|
||||
return value.trim().toLowerCase().normalize("NFC");
|
||||
}
|
||||
|
||||
function normalizeMailText(value: string): string {
|
||||
return value.replace(/\r\n?/gu, "\n").trim().normalize("NFC");
|
||||
}
|
||||
|
||||
function normalizeIdentifier(value: unknown, field: string, maxLength = 191): string {
|
||||
if (typeof value !== "string" || !value || value.trim() !== value || value.length > maxLength || value.includes("\u0000")) {
|
||||
throw new Error(`Portal setup mail ${field} is invalid.`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function normalizeDate(value: unknown): string {
|
||||
if (typeof value !== "string") throw new Error("Portal setup mail expiresAt is invalid.");
|
||||
const parsed = new Date(value);
|
||||
if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== value) {
|
||||
throw new Error("Portal setup mail expiresAt is invalid.");
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function isRawToken(value: string): boolean {
|
||||
return /^[A-Za-z0-9_-]{32,512}$/u.test(value);
|
||||
}
|
||||
|
||||
function isSha256(value: unknown): value is string {
|
||||
return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
|
||||
}
|
||||
|
||||
function sha256(value: string): string {
|
||||
return createHash("sha256").update(value, "utf8").digest("hex");
|
||||
}
|
||||
|
||||
function hashesEqual(actual: string, expected: string): boolean {
|
||||
if (!isSha256(actual) || !isSha256(expected)) return false;
|
||||
return timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(expected, "hex"));
|
||||
}
|
||||
|
||||
function asRecord(value: unknown): Record<string, unknown> | null {
|
||||
return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
|
||||
}
|
||||
Reference in new issue
Block a user