@greensecurity/javascript-sdk 0.46.0-beta.4 → 0.46.0-beta.6

package/src/apps/manifest.ts

@@ -0,0 +1,324 @@
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md.
+ *
+ * The manifest a marketplace app publishes through `POST /api/marketplace/catalog`. Field names
+ * are snake_case because that is what the server stores. Constraints are written as `pattern`s
+ * and `enum`s wherever possible so `manifestJsonSchema` carries them to the server and the CLI
+ * too; the few that JSON Schema cannot express live in `superRefine` and are repeated by the
+ * server's own validation.
+ */
+
+import * as z from "zod/v4";
+import { SURFACES } from "./surfaces.js";
+import {
+  CSP_SOURCE_MAX_CHARS,
+  CSP_SOURCE_PATTERN,
+  CSP_SOURCES_MAX_PER_DIRECTIVE,
+  CSP_SOURCES_MAX_TOTAL_CHARS,
+  cspSourcesTotalChars,
+  HTTPS_URL_PATTERN,
+  isParsableHttpsUrl,
+} from "./url.js";
+
+// The URL and CSP-source rules live in the zod-free `url.ts` so the host renderer can use them
+// without bundling zod; re-exported here because they are part of the manifest contract.
+export {
+  IPV4_OCTET_PATTERN,
+  PORT_PATTERN,
+  CSP_PATH_CHAR,
+  CSP_SOURCE_MAX_CHARS,
+  CSP_SOURCE_PATTERN,
+  CSP_SOURCES_MAX_PER_DIRECTIVE,
+  CSP_SOURCES_MAX_TOTAL_CHARS,
+  cspSourcesTotalChars,
+  HTTPS_URL_PATTERN,
+  isHttpsUrl,
+  isParsableHttpsUrl,
+} from "./url.js";
+
+
+/** A single SRI hash with the digest length its algorithm produces (32, 48 or 64 bytes, base64). */
+export const SRI_PATTERN = "^(sha256-[A-Za-z0-9+/]{43}=|sha384-[A-Za-z0-9+/]{64}|sha512-[A-Za-z0-9+/]{86}==)$";
+/** SemVer 2.0.0 (semver.org's reference pattern): no empty or leading-zero numeric identifiers. */
+export const SEMVER_PATTERN =
+  "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)" +
+  "(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?" +
+  "(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$";
+export const COMPONENT_NAME_PATTERN = "^[A-Za-z_$][A-Za-z0-9_$]*$";
+/**
+ * A positive decimal integer no larger than `Number.MAX_SAFE_INTEGER` (9007199254740991), written
+ * as a string with no leading zeros: up to 15 digits freely, then 16-digit values digit by digit
+ * against the maximum. The server applies the same bound to a string `id`.
+ */
+export const SAFE_INTEGER_STRING_PATTERN =
+  "^(?:[1-9][0-9]{0,14}|[1-8][0-9]{15}|900[0-6][0-9]{12}|90070[0-9]{11}|90071[0-8][0-9]{10}" +
+  "|900719[0-8][0-9]{9}|9007199[0-1][0-9]{8}|90071992[0-4][0-9]{7}|900719925[0-3][0-9]{6}" +
+  "|9007199254[0-6][0-9]{5}|90071992547[0-3][0-9]{4}|9007199254740[0-8][0-9]{2}" +
+  "|90071992547409[0-8][0-9]|9007199254740990|9007199254740991)$";
+export const PERMISSION_PATTERN = "^[a-z0-9_-]+\\.[a-z0-9_-]+$";
+
+/**
+ * Permissions for platform features rather than Green Security data. An app lists them in
+ * `permissions` like any other, and they are granted with the app's role when it is installed.
+ * The server checks them against the app's role only, never against the viewer's role, so they
+ * never appear in a user token's data scope.
+ */
+export const PLATFORM_PERMISSIONS = Object.freeze([
+  {
+    permission: "app_secrets.write",
+    description: "Use the Secret Store: set, find, list and delete this app's secrets, with any token.",
+  },
+] as const);
+
+export type PlatformPermission = (typeof PLATFORM_PERMISSIONS)[number]["permission"];
+
+const PLATFORM_PERMISSION_NAMES: ReadonlySet<string> = new Set(PLATFORM_PERMISSIONS.map((p) => p.permission));
+
+export function isPlatformPermission(value: unknown): value is PlatformPermission {
+  return typeof value === "string" && PLATFORM_PERMISSION_NAMES.has(value);
+}
+const SURFACE_IDS = SURFACES.map((s) => s.id) as [string, ...string[]];
+
+/** Lifecycle events an app's own webhook endpoint can receive (see C19). */
+export const APP_WEBHOOK_EVENTS = [
+  "MarketplaceAppActivation.created",
+  "MarketplaceAppActivation.updated",
+  "MarketplaceAppActivation.destroyed",
+] as const;
+
+export type AppWebhookEvent = (typeof APP_WEBHOOK_EVENTS)[number];
+
+/** Whether an https URL names a DNS host: its last label starts with a letter, so it is no IP literal. */
+function hasNamedHost(value: string): boolean {
+  try {
+    const labels = new URL(value).hostname.split(".");
+    return /^[a-z]/i.test(labels[labels.length - 1] ?? "");
+  } catch {
+    return false;
+  }
+}
+
+/** The JSON Schema keeps the `pattern`; the parse check is TypeScript-side only. */
+export const httpsUrlSchema = z
+  .string()
+  .max(2048)
+  .regex(new RegExp(HTTPS_URL_PATTERN))
+  .refine(isParsableHttpsUrl, { message: "must be a valid https URL" });
+
+/** Rejects a CSP whose sources together would exceed {@link CSP_SOURCES_MAX_TOTAL_CHARS}. */
+export function addCspBudgetIssue(
+  csp: { connect_src?: readonly string[] | undefined; image_src?: readonly string[] | undefined } | undefined,
+  ctx: z.RefinementCtx,
+  path: ReadonlyArray<string | number>,
+): void {
+  const total = cspSourcesTotalChars(csp);
+  if (total > CSP_SOURCES_MAX_TOTAL_CHARS) {
+    ctx.addIssue({
+      code: "custom",
+      path: [...path],
+      message: `connect_src and image_src together use ${total} characters; the limit is ${CSP_SOURCES_MAX_TOTAL_CHARS}`,
+    });
+  }
+}
+
+/** Components may appear on many surfaces, but each surface takes exactly one view. */
+export function addDuplicateViewportIssues(
+  views: ReadonlyArray<{ viewport: string }> | undefined,
+  ctx: z.RefinementCtx,
+  path: ReadonlyArray<string | number>,
+): void {
+  const seen = new Set<string>();
+  views?.forEach((view, i) => {
+    if (seen.has(view.viewport)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [...path, i, "viewport"],
+        message: `duplicate viewport ${view.viewport}; each surface takes one view`,
+      });
+    }
+    seen.add(view.viewport);
+  });
+}
+
+export const cspSourceSchema = z.string().max(CSP_SOURCE_MAX_CHARS).regex(new RegExp(CSP_SOURCE_PATTERN));
+
+export const appViewSchema = z.strictObject({
+  viewport: z.enum(SURFACE_IDS),
+  component: z.string().max(100).regex(new RegExp(COMPONENT_NAME_PATTERN)),
+});
+
+/** Constants are delivered to every view as `environment.constants`. */
+export const appConstantsSchema = z.record(
+  z.string().max(100).regex(/^[A-Za-z_][A-Za-z0-9_]*$/),
+  z.union([z.string().max(2048), z.number(), z.boolean()]),
+);
+
+export const appCspSchema = z.strictObject({
+  connect_src: z.array(cspSourceSchema).max(CSP_SOURCES_MAX_PER_DIRECTIVE).optional(),
+  image_src: z.array(cspSourceSchema).max(CSP_SOURCES_MAX_PER_DIRECTIVE).optional(),
+  /** Accepted for manifests published before v2. Ignored: bundles run from a blob worker. */
+  script_src: z.array(z.string().max(2048)).max(50).optional(),
+  purpose: z.string().min(1).max(1000),
+});
+
+export const appManifestSchema = z
+  .strictObject({
+    id: z.union([z.number().int().positive(), z.string().regex(new RegExp(SAFE_INTEGER_STRING_PATTERN))]),
+    name: z.string().min(1).max(100),
+    icon: httpsUrlSchema,
+    short_description: z.string().min(1).max(500),
+    version: z.string().max(64).regex(new RegExp(SEMVER_PATTERN)).optional(),
+    permissions: z
+      .array(z.strictObject({
+        permission: z.string().max(100).regex(new RegExp(PERMISSION_PATTERN)),
+        purpose: z.string().min(1).max(1000),
+        /**
+         * Why the app cannot work without a sensitive permission (see `isSensitivePermission` in
+         * `review.ts`). Required by the catalog review for a sensitive permission a submission
+         * adds; optional otherwise. Shown to Green Security reviewers and to installers.
+         */
+        justification: z.string().min(1).max(1000).optional(),
+      }))
+      .max(100)
+      .optional(),
+    configuration_instructions: z.string().min(1).max(20000),
+    support_instructions: z.string().min(1).max(20000),
+    constants: appConstantsSchema.optional(),
+    ui_extensions: z
+      .strictObject({
+        bundle: z.strictObject({
+          url: httpsUrlSchema,
+          integrity: z.string().max(200).regex(new RegExp(SRI_PATTERN)),
+        }).optional(),
+        views: z.array(appViewSchema).max(200).optional(),
+        /** Reserved for a future FullPageView. Stored and validated, not rendered. */
+        routes: z
+          .array(z.strictObject({
+            path: z.string().max(200).regex(/^\/[a-z0-9\-/:]*$/),
+            component: z.string().max(100).regex(new RegExp(COMPONENT_NAME_PATTERN)),
+          }))
+          .max(50)
+          .optional(),
+        csp: appCspSchema.optional(),
+      })
+      .optional(),
+    post_install_action: z
+      .strictObject({
+        type: z.enum(["url", "app_settings_view", "app_main_view"]),
+        url: httpsUrlSchema.optional(),
+      })
+      .optional(),
+    // The app's own webhook endpoint: registered by the catalog when the manifest is published, not
+    // tied to any tenant, and sent only this app's lifecycle events. It is how a back-end-only app
+    // hears about its first install. `events` defaults to all of them.
+    webhooks: z
+      .strictObject({
+        url: httpsUrlSchema.refine(hasNamedHost, { message: "must use a DNS host name, not an IP address" }),
+        events: z.array(z.enum(APP_WEBHOOK_EVENTS)).min(1).max(APP_WEBHOOK_EVENTS.length).optional(),
+      })
+      .optional(),
+  })
+  .superRefine((manifest, ctx) => {
+    addDuplicateViewportIssues(manifest.ui_extensions?.views, ctx, ["ui_extensions", "views"]);
+    addCspBudgetIssue(manifest.ui_extensions?.csp, ctx, ["ui_extensions", "csp"]);
+    const events = manifest.webhooks?.events ?? [];
+    if (new Set(events).size !== events.length) {
+      ctx.addIssue({ code: "custom", path: ["webhooks", "events"], message: "events must not repeat" });
+    }
+
+    if (manifest.ui_extensions?.views?.length && !manifest.ui_extensions.bundle) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["ui_extensions", "bundle"],
+        message: "bundle is required when views are declared",
+      });
+    }
+
+    // `version` stays optional only for legacy (v1) manifests. Anything the host renders needs one:
+    // it names the runtime URL and reaches views as `ExtensionContext.app.version`.
+    if ((manifest.ui_extensions?.bundle || manifest.ui_extensions?.views?.length) && !manifest.version) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["version"],
+        message: "version is required when ui_extensions declares a bundle or views",
+      });
+    }
+
+    if (manifest.post_install_action?.type === "url" && !manifest.post_install_action.url) {
+      ctx.addIssue({ code: "custom", path: ["post_install_action", "url"], message: "url is required for type=url" });
+    }
+
+    // A back-end-only app has no views, so it cannot land installers on one. Checked only for
+    // versioned (v2) manifests: v1 apps may carry a post-install view type from before views existed.
+    const viewports = new Set((manifest.ui_extensions?.views ?? []).map((v) => v.viewport));
+    const versioned = manifest.version !== undefined;
+    if (versioned && manifest.post_install_action?.type === "app_settings_view" && !viewports.has("settings")) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["post_install_action", "type"],
+        message: "app_settings_view requires a view for the settings viewport",
+      });
+    }
+    // The settings page is not a main view: a settings-only app should land on app_settings_view.
+    const mainViewports = [...viewports].filter((v) => v !== "settings");
+    if (versioned && manifest.post_install_action?.type === "app_main_view" && mainViewports.length === 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["post_install_action", "type"],
+        message: "app_main_view requires a view other than settings",
+      });
+    }
+  });
+
+export type AppManifestV2 = z.infer<typeof appManifestSchema>;
+
+export type PostInstallAction = NonNullable<AppManifestV2["post_install_action"]>;
+
+/**
+ * What installing the app does when `post_install_action` is left out, so the server and the host
+ * never land an installer on a view the app does not have: nothing for a back-end-only app, the
+ * settings page for a settings-only app, and the app's main view otherwise. `null` means
+ * "no post-install step". An explicit action is returned unchanged.
+ */
+export function effectivePostInstallAction(
+  manifest: Pick<AppManifestV2, "post_install_action" | "ui_extensions">,
+): PostInstallAction | null {
+  if (manifest.post_install_action) return manifest.post_install_action;
+
+  const viewports = (manifest.ui_extensions?.views ?? []).map((v) => v.viewport);
+  if (viewports.some((v) => v !== "settings")) return { type: "app_main_view" };
+  if (viewports.includes("settings")) return { type: "app_settings_view" };
+  return null;
+}
+export type AppView = z.infer<typeof appViewSchema>;
+export type AppConstants = z.infer<typeof appConstantsSchema>;
+
+/**
+ * JSON Schema for the manifest, written to `shared/app-platform/manifest.schema.json` so the
+ * server can validate without TypeScript. The cross-field rules in `superRefine` are not in it.
+ */
+export function manifestJsonSchema(): Record<string, unknown> {
+  return z.toJSONSchema(appManifestSchema, {
+    target: "draft-2020-12",
+    // zod labels every `.regex()` string `format: "regex"`, which in JSON Schema means "this value
+    // is itself a regular expression". The `pattern` it emits alongside is the real constraint.
+    override: (ctx) => {
+      if (ctx.jsonSchema["format"] === "regex") delete ctx.jsonSchema["format"];
+    },
+  }) as Record<string, unknown>;
+}
+
+export type ManifestValidation =
+  | { ok: true; manifest: AppManifestV2 }
+  | { ok: false; issues: Array<{ path: string; message: string }> };
+
+export function validateManifest(input: unknown): ManifestValidation {
+  const result = appManifestSchema.safeParse(input);
+  if (result.success) return { ok: true, manifest: result.data };
+
+  return {
+    ok: false,
+    issues: result.error.issues.map((issue) => ({ path: issue.path.join("."), message: issue.message })),
+  };
+}

package/src/apps/protocol.ts

@@ -0,0 +1,143 @@
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md.
+ *
+ * Two layers travel between the host and a sandbox:
+ *  1. Bootstrap envelopes (`HostToBootstrap` / `BootstrapToHost`): plain JSON between the host
+ *     and the trusted `runtime.html` page, which owns the worker's lifecycle.
+ *  2. Thread messages: `@quilted/threads` traffic between the host and the app's worker, carried
+ *     inside `{ kind: "thread" }` envelopes. `SandboxExports` and `HostApi` are the two sides.
+ */
+
+import type { AppTokens, ExtensionContext } from "./context.js";
+import type { DevSessionDescriptor } from "./devsession.js";
+import type { RouteDescriptor } from "./route.js";
+import type { SurfaceId } from "./surfaces.js";
+
+/**
+ * Structural copy of `@remote-dom/core`'s `RemoteConnection`, so this contract does not pull the
+ * rendering libraries into every SDK consumer. Kept assignable both ways with the real type.
+ */
+export interface RemoteConnection {
+  mutate(records: readonly RemoteMutationRecord[]): void;
+  call(id: string, method: string, ...args: readonly unknown[]): unknown;
+}
+
+/** `@remote-dom/core` mutation records: insert child, remove child, update text, update property. */
+export type RemoteMutationRecord =
+  | readonly [type: 0, parentId: string, child: unknown, index: number]
+  | readonly [type: 1, parentId: string, index: number]
+  | readonly [type: 2, textId: string, text: string]
+  | readonly [type: 3, id: string, name: string, value: unknown, updateType?: 1 | 2 | 3];
+
+export type ViewType = "context" | "focus" | "settings";
+
+/** Implemented inside the worker by the SDK runtime (`defineApp`). */
+export interface SandboxExports {
+  mount(args: {
+    mountId: string;
+    /** Exported component name from the manifest's `views[].component`. */
+    viewComponent: string;
+    surfaceId: SurfaceId;
+    connection: RemoteConnection;
+    context: ExtensionContext;
+    host: HostApi;
+  }): Promise<void>;
+  unmount(mountId: string): Promise<void>;
+  updateContext(mountId: string, patch: Partial<ExtensionContext>): Promise<void>;
+  ping(): Promise<"pong">;
+}
+
+export type ToastType = "success" | "caution" | "pending";
+
+/** Implemented by the host (web-mobile-client). Every method is async across the thread. */
+export interface HostApi {
+  refreshTokens(): Promise<AppTokens>;
+  navigate(to: RouteDescriptor): Promise<void>;
+  /** https only; the host asks the user to confirm. Resolves false when declined or rejected. */
+  openExternalUrl(url: string): Promise<boolean>;
+  /** `message` must be 1–30 characters. */
+  showToast(message: string, opts?: { type?: ToastType }): Promise<void>;
+  /** Invalidates the host's cached data so its screens re-fetch after the app writes. */
+  refreshHostData(): Promise<void>;
+  clipboardWriteText(text: string): Promise<void>;
+  closeView(): Promise<void>;
+}
+
+export const TOAST_MAX_LENGTH = 30;
+
+/** Largest single envelope either side accepts, in UTF-16 code units of its JSON form. */
+export const MAX_ENVELOPE_CHARS = 1_000_000;
+
+export const HEARTBEAT_INTERVAL_MS = 2_000;
+export const HEARTBEAT_MAX_MISSES = 3;
+
+interface InitBase {
+  kind: "init";
+  protocolVersion: ExtensionContext["protocolVersion"];
+  appId: number;
+}
+
+/**
+ * Exactly one code source: the published bundle (checked against its SRI hash), or a dev session
+ * (checked against signed build events) for the developer who owns an active `apps-cli dev`.
+ */
+export type BootstrapInit =
+  | (InitBase & { bundle: { url: string; integrity: string }; devSession?: never })
+  | (InitBase & { devSession: DevSessionDescriptor; bundle?: never });
+
+export type HostToBootstrap =
+  | BootstrapInit
+  | { kind: "thread"; data: unknown }
+  | { kind: "terminate" };
+
+export type BootstrapToHost =
+  | { kind: "ready" }
+  | { kind: "thread"; data: unknown }
+  /** The bundle failed its integrity or signature check and was not executed. */
+  | { kind: "integrity_failed"; reason: string }
+  | { kind: "crashed"; reason: string }
+  /** Dev sessions only: a verified rebuild replaced the worker; the host remounts every view. */
+  | { kind: "reloaded"; seq: number }
+  | { kind: "log"; level: "debug" | "info" | "warn" | "error"; message: string }
+  /** Dev sessions only: build diagnostics from the CLI. */
+  | { kind: "build_error"; diagnostics: Array<{ file?: string; line?: number; message: string }> };
+
+const LOG_LEVELS = new Set(["debug", "info", "warn", "error"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isDiagnostic(value: unknown): boolean {
+  return isRecord(value) && typeof value["message"] === "string" &&
+    (value["file"] === undefined || typeof value["file"] === "string") &&
+    (value["line"] === undefined || Number.isSafeInteger(value["line"]));
+}
+
+/**
+ * Shape check for envelopes the host receives from the sandbox, which is untrusted: every
+ * variant's payload is checked, not just its `kind`. The payload of `thread` is checked by the
+ * thread layer.
+ */
+export function isBootstrapToHost(value: unknown): value is BootstrapToHost {
+  if (!isRecord(value)) return false;
+
+  switch (value["kind"]) {
+    case "ready":
+      return true;
+    case "thread":
+      return "data" in value;
+    case "integrity_failed":
+    case "crashed":
+      return typeof value["reason"] === "string";
+    case "reloaded":
+      return Number.isSafeInteger(value["seq"]);
+    case "log":
+      return typeof value["level"] === "string" && LOG_LEVELS.has(value["level"]) && typeof value["message"] === "string";
+    case "build_error":
+      return Array.isArray(value["diagnostics"]) && value["diagnostics"].every(isDiagnostic);
+    default:
+      return false;
+  }
+}