@voyant-travel/apps 0.1.0

package/dist/ingestion.js

@@ -0,0 +1,232 @@
+import { lookup } from "node:dns/promises";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const DEFAULT_MAX_REDIRECTS = 3;
+const DEFAULT_TIMEOUT_MS = 5000;
+/** Hard transport-level body cap; the caller enforces the tighter manifest cap. */
+const TRANSPORT_MAX_BODY_BYTES = 1024 * 1024;
+const DEFAULT_CONTENT_TYPES = ["application/json", "application/manifest+json"];
+export async function fetchProtectedManifest(inputUrl, options = {}) {
+    const fetcher = options.fetch ?? createPinnedFetch(options.resolveHost);
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    const allowedContentTypes = options.allowedContentTypes ?? DEFAULT_CONTENT_TYPES;
+    let current = requireHttpsUrl(inputUrl);
+    for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount += 1) {
+        await assertPublicHostname(current, options.resolveHost);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        try {
+            const response = await fetcher(current, {
+                method: "GET",
+                redirect: "manual",
+                signal: controller.signal,
+                headers: { accept: "application/json, application/manifest+json" },
+            });
+            if (isRedirect(response.status)) {
+                if (redirectCount === maxRedirects) {
+                    throw new Error("Manifest fetch exceeded the maximum redirect count.");
+                }
+                const location = response.headers.get("location");
+                if (!location)
+                    throw new Error("Manifest redirect did not include a Location header.");
+                current = requireHttpsUrl(new URL(location, current).toString());
+                continue;
+            }
+            if (!response.ok) {
+                throw new Error(`Manifest fetch failed with HTTP ${response.status}.`);
+            }
+            const contentType = response.headers.get("content-type")?.split(";")[0]?.trim() ?? "";
+            if (!allowedContentTypes.includes(contentType)) {
+                throw new Error(`Manifest response content-type "${contentType}" is not allowed.`);
+            }
+            const text = await readBoundedResponse(response, maxBytes);
+            return {
+                url: current,
+                contentType,
+                bytes: new TextEncoder().encode(text).byteLength,
+                body: JSON.parse(text),
+            };
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                throw new Error("Manifest response was not valid JSON.");
+            if (error.name === "AbortError") {
+                throw new Error("Manifest fetch timed out.");
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    throw new Error("Manifest fetch failed.");
+}
+async function readBoundedResponse(response, maxBytes) {
+    const contentLength = response.headers.get("content-length");
+    if (contentLength) {
+        const size = Number(contentLength);
+        if (Number.isFinite(size) && size > maxBytes) {
+            throw new Error("Manifest response exceeded the maximum allowed size.");
+        }
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return response.text();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            total += value.byteLength;
+            if (total > maxBytes)
+                throw new Error("Manifest response exceeded the maximum allowed size.");
+            chunks.push(value);
+        }
+    }
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(body);
+}
+function requireHttpsUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "https:")
+        throw new Error("Manifest URL must use HTTPS.");
+    if (url.username || url.password)
+        throw new Error("Manifest URL must not include credentials.");
+    return url.toString();
+}
+async function assertPublicHostname(value, resolveHost = defaultResolveHost) {
+    const url = new URL(value);
+    if (isPrivateHostname(url.hostname)) {
+        throw new Error("Manifest URL host is not publicly routable.");
+    }
+    const addresses = await resolveHost(url.hostname);
+    if (addresses.length === 0)
+        throw new Error("Manifest URL host did not resolve.");
+    for (const address of addresses) {
+        if (isPrivateAddress(address)) {
+            throw new Error("Manifest URL resolved to a private or reserved address.");
+        }
+    }
+}
+async function defaultResolveHost(hostname) {
+    const result = await lookup(hostname, { all: true, verbatim: true });
+    return result.map((entry) => entry.address);
+}
+/**
+ * A fetch-compatible transport whose socket connects only to addresses that
+ * were validated inside the same DNS resolution. `assertPublicHostname` alone
+ * is a time-of-check/time-of-use guard: a publisher-controlled name can
+ * rebind between the check and the connect. Pinning validation into the
+ * connection `lookup` closes that window.
+ */
+function createPinnedFetch(resolveHost) {
+    const pinnedLookup = (hostname, lookupOptions, callback) => {
+        const resolve = async () => {
+            const addresses = resolveHost
+                ? (await resolveHost(hostname)).map((address) => ({
+                    address,
+                    family: isIP(address) === 6 ? 6 : 4,
+                }))
+                : await lookup(hostname, { all: true, verbatim: true });
+            if (addresses.length === 0) {
+                throw new Error("Manifest URL host did not resolve.");
+            }
+            for (const entry of addresses) {
+                if (isPrivateAddress(entry.address)) {
+                    throw new Error("Manifest URL resolved to a private or reserved address.");
+                }
+            }
+            return addresses;
+        };
+        resolve().then((addresses) => {
+            if (lookupOptions.all) {
+                callback(null, addresses);
+                return;
+            }
+            const first = addresses[0];
+            callback(null, first.address, first.family);
+        }, (error) => callback(error, "", 4));
+    };
+    return (input, init) => new Promise((resolvePromise, rejectPromise) => {
+        const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+        const headers = {};
+        if (init?.headers && !Array.isArray(init.headers) && !(init.headers instanceof Headers)) {
+            Object.assign(headers, init.headers);
+        }
+        const request = httpsRequest({
+            host: url.hostname,
+            port: url.port === "" ? 443 : Number(url.port),
+            path: `${url.pathname}${url.search}`,
+            method: init?.method ?? "GET",
+            headers,
+            signal: init?.signal ?? undefined,
+            lookup: pinnedLookup,
+        }, (incoming) => {
+            const status = incoming.statusCode ?? 0;
+            const responseHeaders = new Headers();
+            for (const [name, value] of Object.entries(incoming.headers)) {
+                if (typeof value === "string")
+                    responseHeaders.set(name, value);
+                else if (Array.isArray(value))
+                    responseHeaders.set(name, value.join(", "));
+            }
+            const chunks = [];
+            let received = 0;
+            incoming.on("data", (chunk) => {
+                received += chunk.byteLength;
+                if (received > TRANSPORT_MAX_BODY_BYTES) {
+                    incoming.destroy();
+                    rejectPromise(new Error("Manifest response exceeded the maximum allowed size."));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            incoming.on("end", () => {
+                const body = status === 204 || status === 304 ? null : new Uint8Array(Buffer.concat(chunks));
+                resolvePromise(new Response(body, { status, headers: responseHeaders }));
+            });
+            incoming.on("error", rejectPromise);
+        });
+        request.on("error", rejectPromise);
+        request.end();
+    });
+}
+function isRedirect(status) {
+    return status >= 300 && status < 400;
+}
+function isPrivateHostname(hostname) {
+    return (hostname === "localhost" ||
+        hostname.endsWith(".localhost") ||
+        hostname.endsWith(".local") ||
+        hostname.endsWith(".internal"));
+}
+function isPrivateAddress(address) {
+    if (isIP(address) === 0)
+        return true;
+    if (address === "::1" || address === "0:0:0:0:0:0:0:1")
+        return true;
+    if (address.startsWith("fc") || address.startsWith("fd") || address.startsWith("fe80:")) {
+        return true;
+    }
+    const parts = address.split(".").map((part) => Number(part));
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part)))
+        return false;
+    const first = parts[0];
+    const second = parts[1];
+    return (first === 10 ||
+        first === 127 ||
+        first === 0 ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168) ||
+        first >= 224);
+}

package/dist/ingestion.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ingestion.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { fetchProtectedManifest } from "./ingestion.js";
+import { validManifest } from "./test-fixtures.js";
+const manifestResponse = (contentType = "application/json") => new Response(JSON.stringify(validManifest), {
+    headers: { "content-type": contentType },
+});
+describe("protected manifest ingestion", () => {
+    it("fetches HTTPS JSON through public DNS and parses bounded content", async () => {
+        const fetcher = async () => manifestResponse();
+        await expect(fetchProtectedManifest("https://app.example.com/manifest.json", {
+            fetch: fetcher,
+            resolveHost: async () => ["203.0.113.10"],
+        })).resolves.toMatchObject({ contentType: "application/json", body: validManifest });
+    });
+    it("rejects private DNS answers, unsafe redirects, oversize bodies, and content types", async () => {
+        await expect(fetchProtectedManifest("https://app.example.com/manifest.json", {
+            fetch: async () => {
+                throw new Error("private DNS should fail before fetch");
+            },
+            resolveHost: async () => ["127.0.0.1"],
+        })).rejects.toThrow(/private or reserved/);
+        await expect(fetchProtectedManifest("https://app.example.com/manifest.json", {
+            fetch: async () => new Response(null, { status: 302, headers: { location: "http://evil.test" } }),
+            resolveHost: async () => ["203.0.113.10"],
+        })).rejects.toThrow(/HTTPS/);
+        await expect(fetchProtectedManifest("https://app.example.com/manifest.json", {
+            fetch: async () => manifestResponse("text/plain"),
+            resolveHost: async () => ["203.0.113.10"],
+        })).rejects.toThrow(/content-type/);
+        await expect(fetchProtectedManifest("https://app.example.com/manifest.json", {
+            fetch: async () => manifestResponse(),
+            maxBytes: 8,
+            resolveHost: async () => ["203.0.113.10"],
+        })).rejects.toThrow(/maximum allowed size/);
+    });
+    it("rejects DNS rebinding between the public pre-check and the pinned connect", async () => {
+        let resolutions = 0;
+        await expect(fetchProtectedManifest("https://app.example.invalid/manifest.json", {
+            timeoutMs: 2000,
+            resolveHost: async () => {
+                resolutions += 1;
+                return resolutions === 1 ? ["203.0.113.10"] : ["10.0.0.7"];
+            },
+        })).rejects.toThrow(/private or reserved/);
+        expect(resolutions).toBeGreaterThanOrEqual(2);
+    });
+});

package/dist/installation-reconciliation.d.ts

@@ -0,0 +1,18 @@
+import { type createCustomFieldsService } from "@voyant-travel/custom-fields";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { AppCredentialInput } from "./installation-service.js";
+import { type AppInstallation, type AppRelease, appAccessCredentials, appExtensionInstallations, appGrants, appWebhookSubscriptions } from "./schema.js";
+type CustomFieldsService = ReturnType<typeof createCustomFieldsService>;
+export interface ReconciliationOptions {
+    customFields?: CustomFieldsService;
+}
+export declare function reconcileRelease(db: PostgresJsDatabase, installation: AppInstallation, release: AppRelease, actorId: string, action: string, options: ReconciliationOptions): Promise<void>;
+export declare function reconcileGrants(db: PostgresJsDatabase, installation: AppInstallation, release: AppRelease, actorId: string, grantedOptionalScopes?: readonly string[]): Promise<void>;
+export declare function newlyRequiredScopes(db: PostgresJsDatabase, installation: AppInstallation, release: AppRelease): Promise<string[]>;
+export declare function rotateCredential(db: PostgresJsDatabase, installation: AppInstallation, credential: AppCredentialInput, actorId: string): Promise<void>;
+export declare function deactivateRuntimeState(db: PostgresJsDatabase, installation: AppInstallation): Promise<void>;
+export declare function deactivateResolvedRegistrations(db: PostgresJsDatabase, installation: AppInstallation): Promise<void>;
+export declare function markAppDefinitionsInactive(db: PostgresJsDatabase, installation: AppInstallation, actorId: string): Promise<void>;
+export declare function countInstallationRows(db: PostgresJsDatabase, table: typeof appGrants | typeof appAccessCredentials | typeof appExtensionInstallations | typeof appWebhookSubscriptions, installationId: string): Promise<number>;
+export declare function audit(db: PostgresJsDatabase, installation: AppInstallation, actorId: string, kind: "lifecycle" | "grant" | "consent" | "credential" | "token" | "reconciliation" | "purge", action: string, details: Record<string, unknown>): Promise<void>;
+export {};

package/dist/installation-reconciliation.js

@@ -0,0 +1,254 @@
+import { createAppCustomFieldDefinitionOwner, customFieldDefinitions, } from "@voyant-travel/custom-fields";
+import { ApiHttpError } from "@voyant-travel/hono";
+import { and, eq, sql } from "drizzle-orm";
+import { appAccessCredentials, appAuditEvents, appExtensionInstallations, appGrants, appOAuthRefreshTokens, appWebhookSubscriptions, } from "./schema.js";
+export async function reconcileRelease(db, installation, release, actorId, action, options) {
+    const normalized = parseNormalizedRelease(release.normalizedRecord);
+    await reconcileCustomFields(db, installation, release, normalized, actorId, options);
+    await reconcileExtensions(db, installation, release, normalized);
+    await reconcileWebhooks(db, installation, release, normalized);
+    await audit(db, installation, actorId, "reconciliation", `manifest.${action}`, {
+        releaseId: release.id,
+        digest: release.manifestDigest,
+        customFields: normalized.customFields.length,
+        extensions: normalized.adminPages.length + normalized.slotExtensions.length,
+        webhooks: normalized.webhooks.length,
+    });
+}
+export async function reconcileGrants(db, installation, release, actorId, grantedOptionalScopes = []) {
+    const normalized = parseNormalizedRelease(release.normalizedRecord);
+    const optional = new Set(normalized.optionalScopes);
+    const grantedOptional = new Set(grantedOptionalScopes);
+    for (const scope of [...normalized.requestedScopes, ...normalized.optionalScopes].sort()) {
+        const isOptional = optional.has(scope);
+        const status = isOptional && !grantedOptional.has(scope) ? "optional" : "granted";
+        await db
+            .insert(appGrants)
+            .values({
+            installationId: installation.id,
+            scope,
+            optional: isOptional,
+            status,
+            grantedAt: status === "granted" ? new Date() : null,
+        })
+            .onConflictDoUpdate({
+            target: [appGrants.installationId, appGrants.scope],
+            set: { status, optional: isOptional, revokedAt: null },
+        });
+    }
+    await audit(db, installation, actorId, "grant", "grants.reconciled", {
+        requested: normalized.requestedScopes,
+        optional: normalized.optionalScopes,
+    });
+}
+export async function newlyRequiredScopes(db, installation, release) {
+    const normalized = parseNormalizedRelease(release.normalizedRecord);
+    const required = new Set(normalized.requestedScopes);
+    const existing = await db
+        .select({ scope: appGrants.scope })
+        .from(appGrants)
+        .where(and(eq(appGrants.installationId, installation.id), eq(appGrants.status, "granted")));
+    for (const grant of existing)
+        required.delete(grant.scope);
+    return [...required].sort();
+}
+export async function rotateCredential(db, installation, credential, actorId) {
+    await db
+        .update(appAccessCredentials)
+        .set({ status: "inactive", deactivatedAt: new Date() })
+        .where(and(eq(appAccessCredentials.installationId, installation.id), eq(appAccessCredentials.status, "active")));
+    const [{ generation = 0 } = {}] = await db
+        .select({ generation: sql `coalesce(max(${appAccessCredentials.generation}), 0)::int` })
+        .from(appAccessCredentials)
+        .where(eq(appAccessCredentials.installationId, installation.id));
+    await db.insert(appAccessCredentials).values({
+        installationId: installation.id,
+        generation: generation + 1,
+        credentialHash: credential.credentialHash,
+        encryptedMetadata: credential.encryptedMetadata,
+        expiresAt: credential.expiresAt ?? null,
+    });
+    await audit(db, installation, actorId, "credential", "credential.rotated", {
+        generation: generation + 1,
+    });
+}
+export async function deactivateRuntimeState(db, installation) {
+    const now = new Date();
+    await db
+        .update(appAccessCredentials)
+        .set({ status: "inactive", deactivatedAt: now })
+        .where(eq(appAccessCredentials.installationId, installation.id));
+    await db
+        .update(appOAuthRefreshTokens)
+        .set({ status: "revoked", revokedAt: now })
+        .where(eq(appOAuthRefreshTokens.installationId, installation.id));
+    await deactivateResolvedRegistrations(db, installation);
+}
+export async function deactivateResolvedRegistrations(db, installation) {
+    const now = new Date();
+    await db
+        .update(appExtensionInstallations)
+        .set({ status: "inactive", deactivatedAt: now })
+        .where(eq(appExtensionInstallations.installationId, installation.id));
+    await db
+        .update(appWebhookSubscriptions)
+        .set({ status: "inactive", deactivatedAt: now })
+        .where(eq(appWebhookSubscriptions.installationId, installation.id));
+}
+export async function markAppDefinitionsInactive(db, installation, actorId) {
+    await db
+        .update(customFieldDefinitions)
+        .set({ lifecycleState: "inactive", updatedAt: new Date() })
+        .where(and(eq(customFieldDefinitions.ownerKind, "app"), eq(customFieldDefinitions.ownerId, installation.appId), eq(customFieldDefinitions.namespace, installation.namespace)));
+    await audit(db, installation, actorId, "reconciliation", "custom_fields.inactive", {});
+}
+export async function countInstallationRows(db, table, installationId) {
+    const [row] = await db
+        .select({ count: sql `count(*)::int` })
+        .from(table)
+        .where(eq(table.installationId, installationId));
+    return row?.count ?? 0;
+}
+export async function audit(db, installation, actorId, kind, action, details) {
+    await db.insert(appAuditEvents).values({
+        installationId: installation.id,
+        appId: installation.appId,
+        deploymentId: installation.deploymentId,
+        actorId,
+        kind,
+        action,
+        details,
+    });
+}
+async function reconcileCustomFields(db, installation, release, normalized, actorId, options) {
+    if (!options.customFields)
+        return;
+    const owner = createAppCustomFieldDefinitionOwner({
+        appId: installation.appId,
+        namespace: installation.namespace,
+        provenance: { source: "app-manifest", releaseId: release.id, reconciledBy: actorId },
+    });
+    const existing = await options.customFields.listForOwner(db, owner, {
+        lifecycleState: "active",
+        limit: 100,
+        offset: 0,
+    });
+    const existingByIdentity = new Map(existing.data.map((definition) => [`${definition.entityType}:${definition.key}`, definition]));
+    const declared = new Set();
+    for (const field of normalized.customFields) {
+        const identity = `${field.entityType}:${field.key}`;
+        declared.add(identity);
+        const existingField = existingByIdentity.get(identity);
+        if (!existingField) {
+            await options.customFields.createForOwner(db, owner, field);
+            continue;
+        }
+        if (existingField.fieldType !== field.fieldType) {
+            throw new ApiHttpError("Custom-field type is immutable once installed", {
+                status: 409,
+                code: "app_custom_field_immutable_type",
+            });
+        }
+        if (field.isRequired && !existingField.isRequired) {
+            throw new ApiHttpError("Custom-field tightening requires migration validation", {
+                status: 409,
+                code: "app_custom_field_tightening_requires_validation",
+            });
+        }
+        await options.customFields.updateForOwner(db, owner, existingField.id, {
+            label: field.label,
+            isRequired: field.isRequired,
+            isSearchable: field.isSearchable,
+            isExportable: field.isExportable,
+            isInvoiceable: field.isInvoiceable,
+            options: field.options,
+        });
+    }
+    for (const [identity, definition] of existingByIdentity) {
+        if (!declared.has(identity)) {
+            await db
+                .update(customFieldDefinitions)
+                .set({ lifecycleState: "deprecated", updatedAt: new Date() })
+                .where(eq(customFieldDefinitions.id, definition.id));
+        }
+    }
+}
+function parseNormalizedRelease(value) {
+    if (!isNormalizedRelease(value)) {
+        throw new ApiHttpError("Stored app release manifest is not a normalized app release", {
+            status: 500,
+            code: "app_release_normalized_record_invalid",
+        });
+    }
+    return value;
+}
+function isNormalizedRelease(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (record.schemaVersion === "voyant.app-release.normalized.v1" &&
+        typeof record.releaseVersion === "string" &&
+        typeof record.digest === "string" &&
+        Array.isArray(record.requestedScopes) &&
+        Array.isArray(record.optionalScopes) &&
+        Array.isArray(record.adminPages) &&
+        Array.isArray(record.slotExtensions) &&
+        Array.isArray(record.webhooks) &&
+        Array.isArray(record.customFields));
+}
+async function reconcileExtensions(db, installation, release, normalized) {
+    for (const page of normalized.adminPages) {
+        await upsertExtension(db, installation, release, `page:${page.key}`, page);
+    }
+    for (const extension of normalized.slotExtensions) {
+        await upsertExtension(db, installation, release, `slot:${extension.key}`, extension);
+    }
+}
+async function upsertExtension(db, installation, release, extensionKey, descriptor) {
+    await db
+        .insert(appExtensionInstallations)
+        .values({
+        installationId: installation.id,
+        releaseId: release.id,
+        extensionKey,
+        descriptor,
+        status: "active",
+        deactivatedAt: null,
+    })
+        .onConflictDoUpdate({
+        target: [appExtensionInstallations.installationId, appExtensionInstallations.extensionKey],
+        set: { releaseId: release.id, descriptor, status: "active", deactivatedAt: null },
+    });
+}
+async function reconcileWebhooks(db, installation, release, normalized) {
+    for (const webhook of normalized.webhooks) {
+        await db
+            .insert(appWebhookSubscriptions)
+            .values({
+            installationId: installation.id,
+            releaseId: release.id,
+            eventType: webhook.eventType,
+            eventVersion: webhook.eventVersion,
+            endpointUrl: webhook.endpointUrl,
+            status: "active",
+            failureCount: 0,
+            pausedAt: null,
+            deactivatedAt: null,
+        })
+            .onConflictDoUpdate({
+            target: [
+                appWebhookSubscriptions.installationId,
+                appWebhookSubscriptions.eventType,
+                appWebhookSubscriptions.eventVersion,
+                appWebhookSubscriptions.endpointUrl,
+            ],
+            set: {
+                releaseId: release.id,
+                status: "active",
+                failureCount: 0,
+                pausedAt: null,
+                deactivatedAt: null,
+            },
+        });
+    }
+}