Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -0,0 +1,70 @@
// VA-P23 · Gmail integration adapter (catalog presence + health).
//
// Same shape as adapters/google-calendar.ts: the Apps-Engine catalog needs a
// registered adapter per app key (drift-free, registry.test.ts), but the HEAVY
// per-USER mailbox sync does NOT run through the generic AppSyncRun path — it
// lives in the email-inbox module (apps/web/app/modules/emailInbox) keyed by
// EmailIntegrationMailbox, because mailboxes are per-user with read_own
// visibility, not per-tenant DataConnections.
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter, type AdapterTokenRefresh } from "@hivegrid/foundation";
import { GmailError, fetchGmailUserInfo, refreshGmailAccessToken, resolveGmailOAuthConfig } from "../google/gmailApi.js";
/** Decrypted credential shape stored (envelope-encrypted) per mailbox. */
export interface GmailCreds {
accessToken: string;
refreshToken: string;
expiresAt?: string | null;
}
function healthFromError(error: unknown): AdapterResult {
if (error instanceof GmailError) {
switch (error.code) {
case "auth_token_expired":
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
case "auth_scope_missing":
return { ok: false, health: "broken", messageKey: "emailInbox.health.scopeMissing" };
case "rate_limit_exceeded":
case "quota_exceeded":
return { ok: true, health: "degraded", messageKey: "emailInbox.health.rateLimited" };
case "provider_outage":
return { ok: false, health: "degraded", messageKey: "emailInbox.health.providerOutage" };
default:
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
}
}
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
}
async function probe(creds: GmailCreds): Promise<AdapterResult> {
if (!creds.accessToken) {
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
}
try {
await fetchGmailUserInfo(creds.accessToken);
return { ok: true, health: "active", messageKey: "emailInbox.health.active" };
} catch (error) {
return healthFromError(error);
}
}
export const gmailAdapter: IntegrationAdapter<GmailCreds> = registerIntegrationAdapter<GmailCreds>({
key: "gmail",
connectionType: "oauth2",
validateConnection: probe,
healthCheck: probe,
refreshToken: async (creds: GmailCreds): Promise<AdapterTokenRefresh<GmailCreds>> => {
const config = resolveGmailOAuthConfig();
if (!config) {
throw new GmailError("not_configured");
}
const next = await refreshGmailAccessToken(config, creds.refreshToken);
return {
creds: { accessToken: next.accessToken, refreshToken: next.refreshToken ?? creds.refreshToken, expiresAt: next.expiresAt.toISOString() },
expiresAt: next.expiresAt,
};
},
// The per-user email-inbox engine (webhook + cron driven) owns the mail sync;
// the generic engine sync is a no-op that reports this in Klartext.
sync: (): Promise<AdapterSyncOutcome> => Promise.resolve({ items: [], summaryKey: "emailInbox.sync.summary.perUserEngine" }),
});
@@ -0,0 +1,73 @@
// AK-P16a · Google Calendar integration adapter (catalog presence + health).
//
// The Apps-Engine catalog needs a registered adapter per app key (drift-free,
// registry.test.ts). The HEAVY per-USER bidirectional sync does NOT run through
// the generic AppSyncRun path — it lives in the calendar module
// (apps/web/app/modules/calendar) keyed by CalendarConnection, because calendar
// connections are per-user with leak-protection, not per-tenant DataConnections.
//
// So this adapter is intentionally thin: it satisfies the contract for catalog
// reachability + lets the platform-admin health surface probe a token, and
// implements OAuth refresh by delegating to googleCalendarApi. `sync()` reports a
// Klartext summary that the per-user engine owns the actual event sync.
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter, type AdapterTokenRefresh } from "@hivegrid/foundation";
import { GoogleCalendarError, listCalendars, refreshAccessToken, resolveGoogleOAuthConfig } from "../google/googleCalendarApi.js";
/** Decrypted credential shape stored (envelope-encrypted) per CalendarConnection. */
export interface GoogleCalendarCreds {
accessToken: string;
refreshToken: string;
expiresAt?: string | null;
}
function healthFromError(error: unknown): AdapterResult {
if (error instanceof GoogleCalendarError) {
switch (error.code) {
case "auth_token_expired":
return { ok: false, health: "broken", messageKey: "calendar.health.tokenExpired" };
case "auth_scope_missing":
return { ok: false, health: "broken", messageKey: "calendar.health.scopeMissing" };
case "rate_limit_exceeded":
return { ok: true, health: "degraded", messageKey: "calendar.health.rateLimited" };
case "provider_outage":
return { ok: false, health: "degraded", messageKey: "calendar.health.providerOutage" };
default:
return { ok: false, health: "broken", messageKey: "calendar.health.unknown" };
}
}
return { ok: false, health: "broken", messageKey: "calendar.health.unknown" };
}
async function probe(creds: GoogleCalendarCreds): Promise<AdapterResult> {
if (!creds.accessToken) {
return { ok: false, health: "broken", messageKey: "calendar.health.tokenExpired" };
}
try {
await listCalendars(creds.accessToken);
return { ok: true, health: "active", messageKey: "calendar.health.active" };
} catch (error) {
return healthFromError(error);
}
}
export const googleCalendarAdapter: IntegrationAdapter<GoogleCalendarCreds> = registerIntegrationAdapter<GoogleCalendarCreds>({
key: "google-calendar",
connectionType: "oauth2",
validateConnection: probe,
healthCheck: probe,
refreshToken: async (creds: GoogleCalendarCreds): Promise<AdapterTokenRefresh<GoogleCalendarCreds>> => {
const config = resolveGoogleOAuthConfig();
if (!config) {
throw new GoogleCalendarError("not_configured");
}
const next = await refreshAccessToken(config, creds.refreshToken);
return {
creds: { accessToken: next.accessToken, refreshToken: next.refreshToken ?? creds.refreshToken, expiresAt: next.expiresAt.toISOString() },
expiresAt: next.expiresAt,
};
},
// The per-user calendar engine (webhook + cron driven) owns event sync; the
// generic engine sync is a no-op that reports this in Klartext.
sync: (): Promise<AdapterSyncOutcome> => Promise.resolve({ items: [], summaryKey: "calendar.sync.summary.perUserEngine" }),
});
@@ -0,0 +1,63 @@
// VA-P23 · Microsoft (Outlook/Graph) mail integration adapter (catalog presence
// + health). Thin like adapters/gmail.ts — the per-user sync engine lives in the
// email-inbox module, this satisfies the catalog/registry drift contract.
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter, type AdapterTokenRefresh } from "@hivegrid/foundation";
import { GraphMailError, fetchGraphUserProfile, refreshMicrosoftAccessToken, resolveMicrosoftMailOAuthConfig } from "../microsoft/graphMailApi.js";
/** Decrypted credential shape stored (envelope-encrypted) per mailbox. */
export interface MicrosoftMailCreds {
accessToken: string;
refreshToken: string;
expiresAt?: string | null;
}
function healthFromError(error: unknown): AdapterResult {
if (error instanceof GraphMailError) {
switch (error.code) {
case "auth_token_expired":
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
case "auth_scope_missing":
return { ok: false, health: "broken", messageKey: "emailInbox.health.scopeMissing" };
case "rate_limit_exceeded":
return { ok: true, health: "degraded", messageKey: "emailInbox.health.rateLimited" };
case "provider_outage":
return { ok: false, health: "degraded", messageKey: "emailInbox.health.providerOutage" };
default:
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
}
}
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
}
async function probe(creds: MicrosoftMailCreds): Promise<AdapterResult> {
if (!creds.accessToken) {
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
}
try {
await fetchGraphUserProfile(creds.accessToken);
return { ok: true, health: "active", messageKey: "emailInbox.health.active" };
} catch (error) {
return healthFromError(error);
}
}
export const microsoftMailAdapter: IntegrationAdapter<MicrosoftMailCreds> = registerIntegrationAdapter<MicrosoftMailCreds>({
key: "microsoft-mail",
connectionType: "oauth2",
validateConnection: probe,
healthCheck: probe,
refreshToken: async (creds: MicrosoftMailCreds): Promise<AdapterTokenRefresh<MicrosoftMailCreds>> => {
const config = resolveMicrosoftMailOAuthConfig();
if (!config) {
throw new GraphMailError("not_configured");
}
const next = await refreshMicrosoftAccessToken(config, creds.refreshToken);
return {
creds: { accessToken: next.accessToken, refreshToken: next.refreshToken ?? creds.refreshToken, expiresAt: next.expiresAt.toISOString() },
expiresAt: next.expiresAt,
};
},
// The per-user email-inbox engine (webhook + cron driven) owns the mail sync.
sync: (): Promise<AdapterSyncOutcome> => Promise.resolve({ items: [], summaryKey: "emailInbox.sync.summary.perUserEngine" }),
});
@@ -0,0 +1,24 @@
import { createHmac } from "node:crypto";
import { describe, expect, it } from "vitest";
import { buildPandaDocAuthHeader, pandaDocByokAdapter, verifyPandaDocWebhookSignature } from "./pandadoc-byok.js";
describe("PandaDoc BYOK adapter", () => {
it("uses the API-Key auth header confirmed by EXT-17", () => {
expect(buildPandaDocAuthHeader("secret")).toBe("API-Key secret");
});
it("validates required BYOK credentials", async () => {
await expect(pandaDocByokAdapter.validateConnection({ apiKey: "k", templateUuid: "tpl" })).resolves.toMatchObject({ ok: true });
await expect(pandaDocByokAdapter.validateConnection({ apiKey: "k" })).resolves.toMatchObject({ ok: false, health: "broken" });
});
it("verifies HMAC SHA-256 webhooks over the raw body", () => {
const rawBody = JSON.stringify({ event: "document.completed", data: { id: "pd-1" } });
const signature = createHmac("sha256", "shared").update(rawBody).digest("hex");
expect(verifyPandaDocWebhookSignature(rawBody, signature, "shared")).toBe(true);
expect(verifyPandaDocWebhookSignature(rawBody, `sha256=${signature}`, "shared")).toBe(true);
expect(verifyPandaDocWebhookSignature(rawBody, signature, "other")).toBe(false);
});
});
@@ -0,0 +1,54 @@
// AK-P16d · optional PandaDoc BYOK adapter.
//
// Plane/EXT-17 confirmed the implementation details used here:
// Authorization: API-Key <key>, template-driven documents, and webhook HMAC
// SHA-256 over the raw request body with the signature supplied by PandaDoc.
import { createHmac, timingSafeEqual } from "node:crypto";
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter } from "@hivegrid/foundation";
export interface PandaDocByokCreds {
readonly apiKey?: string | null;
readonly templateUuid?: string | null;
readonly webhookSharedKey?: string | null;
}
const ACTIVE: AdapterResult = { ok: true, health: "active", messageKey: "integrations.health.active" };
const MISSING: AdapterResult = { ok: false, health: "broken", messageKey: "integrations.health.missingCredentials" };
function validate(creds: PandaDocByokCreds): Promise<AdapterResult> {
if (!creds.apiKey || !creds.templateUuid) {
return Promise.resolve(MISSING);
}
return Promise.resolve(ACTIVE);
}
function normalizeSignature(signature: string): string {
return signature.startsWith("sha256=") ? signature.slice("sha256=".length) : signature;
}
export function buildPandaDocAuthHeader(apiKey: string): string {
return `API-Key ${apiKey}`;
}
export function verifyPandaDocWebhookSignature(rawBody: string | Buffer, signature: string | null | undefined, sharedKey: string | null | undefined): boolean {
if (!signature || !sharedKey) return false;
const expected = createHmac("sha256", sharedKey).update(rawBody).digest("hex");
const received = normalizeSignature(signature);
const expectedBuffer = Buffer.from(expected, "hex");
const receivedBuffer = Buffer.from(received, "hex");
if (expectedBuffer.length !== receivedBuffer.length) return false;
return timingSafeEqual(expectedBuffer, receivedBuffer);
}
export const pandaDocByokAdapter: IntegrationAdapter<PandaDocByokCreds> = registerIntegrationAdapter<PandaDocByokCreds>({
key: "pandadoc-byok",
connectionType: "api_key",
validateConnection: validate,
healthCheck: validate,
sync: (): Promise<AdapterSyncOutcome> =>
Promise.resolve({
items: [],
summaryKey: "integrations.sync.summary.noop",
}),
});
@@ -0,0 +1,34 @@
// R-P5 (P5) — reference integration adapter (the only adapter shipped in v1).
//
// Demonstrates the IntegrationAdapter contract end-to-end (validate / health /
// sync) without any external provider. Concrete adapters (Gmail/AirCall/Mollie)
// follow this shape in their module phases. Registers itself on import (the
// registry barrel imports this for its side effect).
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter } from "@hivegrid/foundation";
type SampleCreds = { baseUrl: string; apiKey: string };
const ACTIVE: AdapterResult = { ok: true, health: "active", messageKey: "integrations.health.active" };
function validate(creds: SampleCreds): Promise<AdapterResult> {
if (!creds.baseUrl || !creds.apiKey) {
return Promise.resolve({ ok: false, health: "broken", messageKey: "integrations.health.missingCredentials" });
}
return Promise.resolve(ACTIVE);
}
export const sampleDataSyncAdapter: IntegrationAdapter<SampleCreds> = registerIntegrationAdapter<SampleCreds>({
key: "sample-data-sync",
connectionType: "rest_api",
validateConnection: validate,
healthCheck: validate,
sync: (): Promise<AdapterSyncOutcome> =>
Promise.resolve({
items: [
{ entityType: "contact", externalId: "ext-1", operation: "created", status: "synced" },
{ entityType: "contact", externalId: "ext-2", operation: "updated", status: "synced" },
],
summaryKey: "integrations.sync.summary.ok",
}),
});
@@ -0,0 +1,24 @@
// AK-P16d · AD-25 default signature adapter.
//
// The hardened SES implementation is local to HiveGrid (touch signature,
// one-time links, email OTP, audit events, sealed PDF + completion certificate).
// This adapter exists so the Apps-Engine catalog/registry can expose and monitor
// the capability without requiring provider credentials.
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter } from "@hivegrid/foundation";
type SesSelfhostedCreds = Record<string, never>;
const ACTIVE: AdapterResult = { ok: true, health: "active", messageKey: "integrations.health.active" };
export const sesSelfhostedAdapter: IntegrationAdapter<SesSelfhostedCreds> = registerIntegrationAdapter<SesSelfhostedCreds>({
key: "ses-selfhosted",
connectionType: "rest_api",
validateConnection: () => Promise.resolve(ACTIVE),
healthCheck: () => Promise.resolve(ACTIVE),
sync: (): Promise<AdapterSyncOutcome> =>
Promise.resolve({
items: [],
summaryKey: "integrations.sync.summary.noop",
}),
});