@voyant-travel/apps 0.1.0

package/dist/app-api-service.js

@@ -0,0 +1,231 @@
+import { createAppCustomFieldDefinitionOwner, createCustomFieldsService, } from "@voyant-travel/custom-fields";
+import { ApiHttpError } from "@voyant-travel/hono";
+import { and, asc, eq, sql } from "drizzle-orm";
+import { assertActiveAppInstallationAccess } from "./access-boundary.js";
+import { APP_API_VERSION } from "./app-api-contracts.js";
+import { appAuditEvents, appGrants, appReleases, appWebhookSubscriptions } from "./schema.js";
+const DEFAULT_RATE_LIMIT = { installationLimit: 120, appLimit: 600, windowMs: 60_000 };
+const REMOTE_APP_NAMESPACE = /^\$app(?::[a-z][a-z0-9-]*)?$/;
+const PHYSICAL_APP_NAMESPACE = /^app--/;
+const buckets = new Map();
+export function createAppApiService(options = {}) {
+    const now = () => options.now?.() ?? new Date();
+    const customFields = options.customFieldTargets &&
+        createCustomFieldsService(options.customFieldTargets, options.customFieldValueLifecycles ?? [], options.customFieldValueOperations ?? []);
+    async function introspect(db, context) {
+        const access = await requireAccess(db, context, ["app-installation:read"]);
+        const grants = await db
+            .select({
+            scope: appGrants.scope,
+            status: appGrants.status,
+            optional: appGrants.optional,
+        })
+            .from(appGrants)
+            .where(eq(appGrants.installationId, context.installationId))
+            .orderBy(appGrants.scope);
+        return {
+            data: {
+                installation: {
+                    id: access.installation.id,
+                    appId: access.installation.appId,
+                    status: access.installation.status,
+                    namespace: access.installation.namespace,
+                    deploymentId: access.installation.deploymentId,
+                },
+                release: {
+                    id: access.release.id,
+                    version: access.release.releaseVersion,
+                    apiCompatibility: access.release.apiCompatibility,
+                },
+                grants,
+            },
+        };
+    }
+    async function listEntities(db, context, entity, query) {
+        await requireAccess(db, context, [`${entity}:read`]);
+        const reader = options.entityReaders?.[entity];
+        if (!reader)
+            throw notSupported(`Entity "${entity}" is not supported by the App API.`);
+        return { data: await reader.list(db, query) };
+    }
+    async function listFinanceDocuments(db, context, query) {
+        await requireAccess(db, context, ["finance-documents:read"]);
+        if (!options.finance)
+            throw notSupported("Finance App API runtime is not configured.");
+        return { data: await options.finance.listDocuments(db, query) };
+    }
+    async function executeFinanceAction(db, context, input) {
+        await requireAccess(db, context, [`finance-actions:${input.action}`]);
+        if (!options.finance)
+            throw notSupported("Finance App API runtime is not configured.");
+        if (!input.approvalId) {
+            throw new ApiHttpError("Finance action requires action-ledger approval.", {
+                status: 403,
+                code: "app_api_finance_approval_required",
+            });
+        }
+        return { data: await options.finance.executeAction(db, input) };
+    }
+    async function listCustomFieldDefinitions(db, context, query) {
+        const access = await requireAccess(db, context, ["custom-field-definitions:read"]);
+        return customFieldsRequired().listForOwner(db, owner(access), query);
+    }
+    async function createCustomFieldDefinition(db, context, namespace, input) {
+        assertAppNamespaceAlias(namespace);
+        const access = await requireAccess(db, context, ["custom-field-definitions:write"]);
+        return { data: await customFieldsRequired().createForOwner(db, owner(access), input) };
+    }
+    async function updateCustomFieldDefinition(db, context, id, namespace, input) {
+        assertAppNamespaceAlias(namespace);
+        const access = await requireAccess(db, context, ["custom-field-definitions:write"]);
+        const data = await customFieldsRequired().updateForOwner(db, owner(access), id, input);
+        if (!data)
+            throw notFound("Custom-field definition not found.");
+        return { data };
+    }
+    async function listCustomFieldValues(db, context, query) {
+        await requireAccess(db, context, [`custom-field-values:${query.entityType ?? "read"}`]);
+        const access = await requireAccess(db, context, ["custom-field-values:read"]);
+        return customFieldsRequired().values.listForOwner(db, owner(access), query);
+    }
+    async function upsertCustomFieldValue(db, context, definitionId, input) {
+        await requireAccess(db, context, [
+            "custom-field-values:write",
+            `custom-field-values:${input.entityType}`,
+        ]);
+        const access = await requireAccess(db, context, []);
+        return {
+            data: await customFieldsRequired().values.upsertForOwner(db, owner(access), definitionId, input),
+        };
+    }
+    async function listWebhookHealth(db, context) {
+        await requireAccess(db, context, ["webhooks:read"]);
+        const data = await db
+            .select()
+            .from(appWebhookSubscriptions)
+            .where(eq(appWebhookSubscriptions.installationId, context.installationId))
+            .orderBy(asc(appWebhookSubscriptions.eventType));
+        return { data };
+    }
+    async function listAuditHistory(db, context, query) {
+        await requireAccess(db, context, ["app-audit:read"]);
+        const where = and(eq(appAuditEvents.appId, context.appId), eq(appAuditEvents.installationId, context.installationId));
+        const [data, count] = await Promise.all([
+            db.select().from(appAuditEvents).where(where).limit(query.limit).offset(query.offset),
+            db.select({ count: sql `count(*)::int` }).from(appAuditEvents).where(where),
+        ]);
+        return { data, total: count[0]?.count ?? 0, limit: query.limit, offset: query.offset };
+    }
+    return {
+        introspect,
+        listEntities,
+        listFinanceDocuments,
+        executeFinanceAction,
+        listCustomFieldDefinitions,
+        createCustomFieldDefinition,
+        updateCustomFieldDefinition,
+        listCustomFieldValues,
+        upsertCustomFieldValue,
+        listWebhookHealth,
+        listAuditHistory,
+        requireAccess,
+        enforceRateLimit,
+    };
+    async function requireAccess(db, context, requiredScopes) {
+        enforceRateLimit(context);
+        const installation = await assertActiveAppInstallationAccess(db, {
+            installationId: context.installationId,
+            requiredScopes,
+        });
+        if (installation.appId !== context.appId || installation.releaseId !== context.releaseId) {
+            throw new ApiHttpError("App token does not match the active installation.", {
+                status: 403,
+                code: "app_api_token_installation_mismatch",
+            });
+        }
+        const [release] = await db
+            .select()
+            .from(appReleases)
+            .where(eq(appReleases.id, installation.releaseId))
+            .limit(1);
+        if (!release)
+            throw notFound("Installed app release not found.");
+        assertCompatibleVersion(context.apiVersion ?? APP_API_VERSION, release.apiCompatibility);
+        return { installation, release };
+    }
+    function enforceRateLimit(context) {
+        const policy = options.rateLimit ?? DEFAULT_RATE_LIMIT;
+        hit(`installation:${context.installationId}`, policy.installationLimit, policy.windowMs);
+        hit(`app:${context.appId}`, policy.appLimit, policy.windowMs);
+    }
+    function hit(key, limit, windowMs) {
+        const timestamp = now().getTime();
+        const bucket = buckets.get(key);
+        if (!bucket || bucket.resetAt <= timestamp) {
+            buckets.set(key, { count: 1, resetAt: timestamp + windowMs });
+            return;
+        }
+        if (bucket.count >= limit) {
+            throw new ApiHttpError("App API rate limit exceeded.", {
+                status: 429,
+                code: "app_api_rate_limited",
+                details: { key, resetAt: new Date(bucket.resetAt).toISOString() },
+            });
+        }
+        bucket.count += 1;
+    }
+    function owner(access) {
+        return createAppCustomFieldDefinitionOwner({
+            appId: access.installation.appId,
+            namespace: access.installation.namespace,
+        });
+    }
+    function customFieldsRequired() {
+        if (!customFields)
+            throw notSupported("Custom fields App API runtime is not configured.");
+        return customFields;
+    }
+}
+export function assertAppNamespaceAlias(namespace) {
+    if (!namespace || namespace === "$app")
+        return;
+    if (PHYSICAL_APP_NAMESPACE.test(namespace) || !REMOTE_APP_NAMESPACE.test(namespace)) {
+        throw new ApiHttpError("App APIs accept only the server-resolved $app namespace alias.", {
+            status: 400,
+            code: "app_api_invalid_custom_field_namespace",
+        });
+    }
+}
+export function assertCompatibleVersion(requested, range) {
+    if (requested < range.min || requested > range.max) {
+        throw new ApiHttpError("Requested App API version is outside the installed release range.", {
+            status: 426,
+            code: "app_api_version_out_of_range",
+            details: { requested, supported: range },
+        });
+    }
+}
+export async function withAppApiDeadline(promise, timeoutMs = 5_000) {
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => reject(new ApiHttpError("App API request deadline exceeded.", {
+                    status: 504,
+                    code: "app_api_deadline_exceeded",
+                })), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function notSupported(message) {
+    return new ApiHttpError(message, { status: 501, code: "app_api_not_configured" });
+}
+function notFound(message) {
+    return new ApiHttpError(message, { status: 404, code: "not_found" });
+}

package/dist/app-api-service.test.d.ts

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

package/dist/app-api-service.test.js

@@ -0,0 +1,105 @@
+import { ApiHttpError } from "@voyant-travel/hono";
+import { describe, expect, it, vi } from "vitest";
+import { assertAppNamespaceAlias, assertCompatibleVersion, createAppApiService, } from "./app-api-service.js";
+import { appGrants, appInstallations, appReleases } from "./schema.js";
+function postgresStub(implementation) {
+    const db = Object.create(null);
+    Object.assign(db, implementation);
+    return db;
+}
+function createAccessDb(options) {
+    const installation = {
+        id: "inst_1",
+        appId: "app_1",
+        deploymentId: "dep_1",
+        releaseId: "rel_1",
+        status: options.status ?? "active",
+        namespace: "app--one",
+    };
+    const release = {
+        id: "rel_1",
+        appId: "app_1",
+        releaseVersion: "1.0.0",
+        apiCompatibility: options.releaseRange ?? { min: "2026-07-01", max: "2026-12-31" },
+    };
+    return postgresStub({
+        select: () => ({
+            from: (table) => ({
+                where: () => {
+                    const rows = () => {
+                        if (table === appInstallations)
+                            return [installation];
+                        if (table === appReleases)
+                            return [release];
+                        if (table === appGrants)
+                            return (options.scopes ?? []).map((scope) => ({ scope }));
+                        return [];
+                    };
+                    return {
+                        // biome-ignore lint/suspicious/noThenProperty: test stub models Drizzle's awaitable query builder -- owner: apps.
+                        then: (resolve) => Promise.resolve(rows()).then(resolve),
+                        orderBy: async () => rows(),
+                        limit: async () => rows(),
+                    };
+                },
+            }),
+        }),
+    });
+}
+const context = {
+    appId: "app_1",
+    installationId: "inst_1",
+    releaseId: "rel_1",
+    tokenMode: "offline",
+    scopes: [],
+    apiVersion: "2026-07-01",
+};
+describe("App API service boundary", () => {
+    it("rejects direct service calls when the installation is inactive", async () => {
+        const service = createAppApiService();
+        await expect(service.requireAccess(createAccessDb({ status: "paused", scopes: ["app-installation:read"] }), context, ["app-installation:read"])).rejects.toMatchObject({ status: 403, code: "app_installation_not_active" });
+    });
+    it("rejects direct service calls when required scopes are not granted", async () => {
+        const service = createAppApiService();
+        await expect(service.requireAccess(createAccessDb({ scopes: [] }), context, ["app-installation:read"])).rejects.toMatchObject({ status: 403, code: "app_installation_scope_missing" });
+    });
+    it("fails closed when the requested API version is outside the installed release range", async () => {
+        const service = createAppApiService();
+        await expect(service.requireAccess(createAccessDb({
+            scopes: ["app-installation:read"],
+            releaseRange: { min: "2026-08-01", max: "2026-12-31" },
+        }), context, ["app-installation:read"])).rejects.toMatchObject({ status: 426, code: "app_api_version_out_of_range" });
+    });
+    it("requires action-ledger approval for finance actions even when OAuth scope is granted", async () => {
+        const executeAction = vi.fn();
+        const service = createAppApiService({
+            finance: { listDocuments: vi.fn(), executeAction },
+        });
+        await expect(service.executeFinanceAction(createAccessDb({ scopes: ["finance-actions:issue"] }), context, {
+            action: "issue",
+            idempotencyKey: "idem_1",
+            payload: {},
+        })).rejects.toMatchObject({ status: 403, code: "app_api_finance_approval_required" });
+        expect(executeAction).not.toHaveBeenCalled();
+    });
+    it("isolates rate limits per installation", async () => {
+        const service = createAppApiService({
+            rateLimit: { installationLimit: 1, appLimit: 10, windowMs: 60_000 },
+        });
+        const rateContext = { ...context, appId: "rate_app", installationId: "rate_inst_1" };
+        service.enforceRateLimit(rateContext);
+        expect(() => service.enforceRateLimit(rateContext)).toThrow(ApiHttpError);
+        expect(() => service.enforceRateLimit({ ...rateContext, installationId: "rate_inst_2" })).not.toThrow();
+    });
+    it("accepts only the $app custom-field namespace alias from request data", () => {
+        expect(() => assertAppNamespaceAlias(undefined)).not.toThrow();
+        expect(() => assertAppNamespaceAlias("$app")).not.toThrow();
+        expect(() => assertAppNamespaceAlias("$app:sync")).not.toThrow();
+        expect(() => assertAppNamespaceAlias("app--foreign")).toThrow(ApiHttpError);
+        expect(() => assertAppNamespaceAlias("custom")).toThrow(ApiHttpError);
+    });
+    it("compares App API compatibility ranges inclusively", () => {
+        expect(() => assertCompatibleVersion("2026-07-01", { min: "2026-07-01", max: "2026-12-31" })).not.toThrow();
+        expect(() => assertCompatibleVersion("2027-01-01", { min: "2026-07-01", max: "2026-12-31" })).toThrow(ApiHttpError);
+    });
+});

package/dist/compiler.d.ts

@@ -0,0 +1,38 @@
+import type { VoyantGraphEventCatalog } from "@voyant-travel/core/project";
+import { type AppManifest } from "./contracts.js";
+export interface CompiledAppManifest {
+    manifest: AppManifest;
+    canonicalJson: string;
+    digest: string;
+    normalizedRelease: NormalizedAppReleaseRecord;
+}
+export interface NormalizedAppReleaseRecord {
+    schemaVersion: "voyant.app-release.normalized.v1";
+    manifestSchemaVersion: AppManifest["schemaVersion"];
+    releaseVersion: string;
+    digest: string;
+    apiCompatibility: AppManifest["apiCompatibility"];
+    requestedScopes: readonly string[];
+    optionalScopes: readonly string[];
+    adminPages: AppManifest["admin"]["pages"];
+    slotExtensions: AppManifest["admin"]["slotExtensions"];
+    webhooks: AppManifest["webhooks"];
+    customFields: AppManifest["customFields"];
+    defaultLocale: string;
+    supportedLocales: readonly string[];
+    localizations: readonly NormalizedLocalization[];
+    urls: AppManifest["urls"];
+    data: AppManifest["data"];
+}
+export interface NormalizedLocalization {
+    locale: string;
+    surface: string;
+    messageKey: string;
+    text: string;
+}
+export interface CompileAppManifestOptions {
+    eventCatalog?: VoyantGraphEventCatalog;
+}
+export declare function compileAppManifest(input: unknown, options?: CompileAppManifestOptions): CompiledAppManifest;
+export declare function canonicalJsonStringify(value: unknown): string;
+export declare function canonicalize(value: unknown): unknown;

package/dist/compiler.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { isExternalWebhookPayloadSchema } from "@voyant-travel/core/project";
+import { z } from "zod";
+import { appManifestSchema } from "./contracts.js";
+export function compileAppManifest(input, options = {}) {
+    const manifest = appManifestSchema.parse(input);
+    validateWebhookSubscriptions(manifest, options.eventCatalog);
+    const normalized = normalizeManifest(manifest);
+    const canonicalJson = canonicalJsonStringify(normalized);
+    const digest = `sha256:${createHash("sha256").update(canonicalJson).digest("hex")}`;
+    return {
+        manifest,
+        canonicalJson,
+        digest,
+        normalizedRelease: {
+            schemaVersion: "voyant.app-release.normalized.v1",
+            manifestSchemaVersion: manifest.schemaVersion,
+            releaseVersion: manifest.releaseVersion,
+            digest,
+            apiCompatibility: manifest.apiCompatibility,
+            requestedScopes: normalized.scopes.requested,
+            optionalScopes: normalized.scopes.optional,
+            adminPages: normalized.admin.pages,
+            slotExtensions: normalized.admin.slotExtensions,
+            webhooks: normalized.webhooks,
+            customFields: normalized.customFields,
+            defaultLocale: normalized.locales.default,
+            supportedLocales: normalized.locales.supported,
+            localizations: flattenLocalizations(normalized),
+            urls: normalized.urls,
+            data: normalized.data,
+        },
+    };
+}
+export function canonicalJsonStringify(value) {
+    return JSON.stringify(canonicalize(value));
+}
+export function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map((item) => canonicalize(item));
+    if (!value || typeof value !== "object")
+        return value;
+    const record = value;
+    return Object.fromEntries(Object.keys(record)
+        .sort()
+        .map((key) => [key, canonicalize(record[key])]));
+}
+function normalizeManifest(manifest) {
+    return {
+        ...manifest,
+        scopes: {
+            requested: sortedUnique(manifest.scopes.requested),
+            optional: sortedUnique(manifest.scopes.optional),
+        },
+        admin: {
+            pages: [...manifest.admin.pages].sort(byKey),
+            slotExtensions: [...manifest.admin.slotExtensions]
+                .map((extension) => ({ ...extension, slots: sortedUnique(extension.slots) }))
+                .sort(byKey),
+        },
+        webhooks: [...manifest.webhooks].sort((left, right) => `${left.eventType}:${left.eventVersion}`.localeCompare(`${right.eventType}:${right.eventVersion}`)),
+        customFields: [...manifest.customFields].sort((left, right) => `${left.entityType}:${left.logicalNamespace ?? ""}:${left.key}`.localeCompare(`${right.entityType}:${right.logicalNamespace ?? ""}:${right.key}`)),
+        locales: {
+            default: manifest.locales.default,
+            supported: sortedUnique(manifest.locales.supported),
+            host: Object.fromEntries(Object.entries(manifest.locales.host).sort(([left], [right]) => left.localeCompare(right))),
+        },
+        data: {
+            ...manifest.data,
+            classifications: sortedUnique(manifest.data.classifications),
+        },
+    };
+}
+function validateWebhookSubscriptions(manifest, eventCatalog) {
+    if (!eventCatalog)
+        return;
+    const externalEvents = new Map();
+    for (const event of eventCatalog.events) {
+        if (event.visibility === "external" && isExternalWebhookPayloadSchema(event.payloadSchema)) {
+            externalEvents.set(`${event.eventType}:${event.version}`, event);
+        }
+    }
+    for (const subscription of manifest.webhooks) {
+        if (!externalEvents.has(`${subscription.eventType}:${subscription.eventVersion}`)) {
+            throw new z.ZodError([
+                {
+                    code: "custom",
+                    path: ["webhooks"],
+                    message: `Webhook subscription "${subscription.eventType}" version "${subscription.eventVersion}" is not an external event contract in the selected graph.`,
+                    input: subscription,
+                },
+            ]);
+        }
+    }
+}
+function flattenLocalizations(manifest) {
+    const rows = [];
+    for (const [locale, metadata] of Object.entries(manifest.locales.host)) {
+        rows.push({ locale, surface: "app", messageKey: "name", text: metadata.name });
+        rows.push({ locale, surface: "app", messageKey: "summary", text: metadata.summary });
+        for (const [key, text] of Object.entries(metadata.navigation)) {
+            rows.push({ locale, surface: "navigation", messageKey: key, text });
+        }
+        for (const [key, text] of Object.entries(metadata.extensions)) {
+            rows.push({ locale, surface: "extension", messageKey: key, text });
+        }
+        for (const [key, text] of Object.entries(metadata.setup)) {
+            rows.push({ locale, surface: "setup", messageKey: key, text });
+        }
+    }
+    return rows.sort((left, right) => `${left.locale}:${left.surface}:${left.messageKey}`.localeCompare(`${right.locale}:${right.surface}:${right.messageKey}`));
+}
+function sortedUnique(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function byKey(left, right) {
+    return left.key.localeCompare(right.key);
+}

package/dist/compiler.test.d.ts

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

package/dist/compiler.test.js

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { compileAppManifest } from "./compiler.js";
+import { appManifestSchema } from "./contracts.js";
+import { validManifest } from "./test-fixtures.js";
+describe("app manifest compiler", () => {
+    it("accepts a closed v1 manifest and produces a stable digest", () => {
+        const first = compileAppManifest(validManifest);
+        const second = compileAppManifest({
+            ...validManifest,
+            scopes: { optional: ["invoices:read"], requested: ["bookings:read"] },
+        });
+        expect(first.digest).toMatch(/^sha256:/);
+        expect(second.digest).toBe(first.digest);
+        expect(first.normalizedRelease.defaultLocale).toBe("en-US");
+        expect(first.normalizedRelease.localizations).toEqual(expect.arrayContaining([
+            expect.objectContaining({ locale: "en-US", surface: "app", messageKey: "name" }),
+            expect.objectContaining({
+                locale: "en-US",
+                surface: "extension",
+                messageKey: "booking-panel",
+            }),
+        ]));
+    });
+    it("rejects forbidden declaration classes with actionable paths", () => {
+        const result = appManifestSchema.safeParse({
+            ...validManifest,
+            migrations: ["001.sql"],
+            providers: [{ role: "database" }],
+            scripts: { postinstall: "node install.js" },
+            dependencies: { leftpad: "1.0.0" },
+            exports: { ".": "./index.js" },
+            files: ["dist/index.js"],
+        });
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            expect(result.error.issues.map((issue) => issue.path.join("."))).toEqual(expect.arrayContaining(["migrations", "providers", "scripts", "dependencies", "exports"]));
+            expect(result.error.issues.map((issue) => issue.message).join("\n")).toContain("forbidden");
+        }
+    });
+    it("validates slot ids and external webhook event versions", () => {
+        expect(() => compileAppManifest({
+            ...validManifest,
+            admin: {
+                ...validManifest.admin,
+                slotExtensions: [{ ...validManifest.admin.slotExtensions[0], slots: ["unknown.slot"] }],
+            },
+        })).toThrow();
+        expect(() => compileAppManifest(validManifest, {
+            eventCatalog: {
+                schemaVersion: "voyant.event-catalog.v1",
+                events: [
+                    {
+                        key: "booking.created@2.0.0",
+                        id: "event.booking.created",
+                        unitId: "@voyant-travel/bookings",
+                        packageName: "@voyant-travel/bookings",
+                        eventType: "booking.created",
+                        version: "2.0.0",
+                        payloadSchema: { type: "object", properties: {} },
+                        visibility: "external",
+                        audit: { sourceModule: "@voyant-travel/bookings", category: "domain" },
+                        redactedFields: [],
+                    },
+                ],
+            },
+        })).toThrow(/not an external event contract/);
+        expect(() => compileAppManifest(validManifest, {
+            eventCatalog: {
+                schemaVersion: "voyant.event-catalog.v1",
+                events: [
+                    {
+                        key: "booking.created@1.0.0",
+                        id: "event.booking.created",
+                        unitId: "@voyant-travel/bookings",
+                        packageName: "@voyant-travel/bookings",
+                        eventType: "booking.created",
+                        version: "1.0.0",
+                        payloadSchema: { type: "object", properties: {} },
+                        visibility: "internal",
+                        audit: { sourceModule: "@voyant-travel/bookings", category: "domain" },
+                        redactedFields: [],
+                    },
+                ],
+            },
+        })).toThrow(/not an external event contract/);
+    });
+    it("rejects webhook endpoints that target local infrastructure", () => {
+        expect(() => compileAppManifest({
+            ...validManifest,
+            webhooks: [
+                {
+                    eventType: "booking.created",
+                    eventVersion: "1.0.0",
+                    endpointUrl: "https://127.0.0.1/webhooks/voyant",
+                },
+            ],
+        })).toThrow(/local or private hosts/);
+    });
+});

package/dist/consent.d.ts

@@ -0,0 +1,15 @@
+import type { AccessCatalog } from "@voyant-travel/types/api-keys";
+import type { AppRelease } from "./schema.js";
+export interface ConsentComputationInput {
+    release: AppRelease;
+    accessCatalog: AccessCatalog;
+    operatorGrantedScopes: readonly string[];
+    grantedOptionalScopes?: readonly string[];
+}
+export interface ComputedConsent {
+    requiredScopes: string[];
+    optionalScopes: string[];
+    grantedScopes: string[];
+    deniedOptionalScopes: string[];
+}
+export declare function computeAppConsent(input: ConsentComputationInput): ComputedConsent;

package/dist/consent.js

@@ -0,0 +1,50 @@
+import { ApiHttpError } from "@voyant-travel/hono";
+export function computeAppConsent(input) {
+    const normalized = parseReleaseScopes(input.release.normalizedRecord);
+    const remoteSafe = remoteSafeScopes(input.accessCatalog);
+    const operatorGranted = new Set(input.operatorGrantedScopes);
+    const optionalGrantRequest = new Set(input.grantedOptionalScopes ?? []);
+    const requiredScopes = normalized.requestedScopes.filter((scope) => canGrantScope(scope, remoteSafe, operatorGranted));
+    const missingRequired = normalized.requestedScopes.filter((scope) => !requiredScopes.includes(scope));
+    if (missingRequired.length > 0) {
+        throw new ApiHttpError("Required app scopes are not grantable for remote apps", {
+            status: 403,
+            code: "app_required_scope_not_grantable",
+            details: { scopes: missingRequired },
+        });
+    }
+    const optionalScopes = normalized.optionalScopes.filter((scope) => canGrantScope(scope, remoteSafe, operatorGranted));
+    const grantedOptional = optionalScopes.filter((scope) => optionalGrantRequest.has(scope));
+    const deniedOptionalScopes = normalized.optionalScopes.filter((scope) => !grantedOptional.includes(scope));
+    const grantedScopes = Array.from(new Set([...requiredScopes, ...grantedOptional])).sort();
+    return {
+        requiredScopes: requiredScopes.sort(),
+        optionalScopes: optionalScopes.sort(),
+        grantedScopes,
+        deniedOptionalScopes: deniedOptionalScopes.sort(),
+    };
+}
+function canGrantScope(scope, remoteSafe, operatorGranted) {
+    return remoteSafe.has(scope) && operatorGranted.has(scope);
+}
+function remoteSafeScopes(catalog) {
+    const catalogScopes = new Set(catalog.resources.flatMap((resource) => resource.actions.map((action) => `${resource.resource}:${action.action}`)));
+    const presetScopes = catalog.presets
+        .filter((preset) => preset.kind === "api-token-grant" && Boolean(preset.audience))
+        .flatMap((preset) => preset.grants);
+    return new Set(presetScopes.filter((scope) => catalogScopes.has(scope)));
+}
+function parseReleaseScopes(value) {
+    if (!value || typeof value !== "object")
+        return { requestedScopes: [], optionalScopes: [] };
+    const record = value;
+    return {
+        requestedScopes: stringArray(record.requestedScopes),
+        optionalScopes: stringArray(record.optionalScopes),
+    };
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? Array.from(new Set(value.filter((item) => typeof item === "string"))).sort()
+        : [];
+}

package/dist/consent.test.d.ts

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