@greensecurity/javascript-sdk 0.46.0-beta.5 → 0.46.0-beta.7

package/src/apps/secrets/index.ts

@@ -0,0 +1,520 @@
+/*
+ * Hand-written (not generated by Speakeasy). Third-party app developer kit (C10); see
+ * docs/third-party-apps/plan.md.
+ *
+ * Import as `@greensecurity/javascript-sdk/apps/secrets`.
+ *
+ * Helpers for the App Secret Store (C3): `POST /api/apps/secrets`, `GET /api/apps/secrets/find`,
+ * `POST /api/apps/secrets/delete` and `GET /api/apps/secrets`. They are written by hand over the
+ * SDK core request path because the generated SDK does not carry these operations yet.
+ * TODO(C11): once the regenerated SDK includes the `apps` operations (`setAppSecret`,
+ * `findAppSecret`, `deleteAppSecret`, `listAppSecrets`), re-export those instead and delete
+ * this module's request code.
+ *
+ * ```ts
+ * const ctx = useExtensionContext();
+ * await secrets.set(ctx, { name: "api_key", payload: key, scope: { type: "installation" } });
+ * const { payload } = await secrets.find(ctx, { name: "api_key", scope: { type: "installation" } });
+ * ```
+ *
+ * **Permission.** Every Secret Store call needs the platform permission `app_secrets.write`
+ * (C0's `PLATFORM_PERMISSIONS`). Declare it in the manifest's `permissions`, for example
+ * `{ "permission": "app_secrets.write", "purpose": "Store your Acme API key." }`; it is granted
+ * with the app's role when the app is installed. Without it the store answers 403 "This app has
+ * not been granted app_secrets.write." to every token kind (user, installation and service
+ * account alike), and these helpers reject with a {@link SecretsPermissionError}. The server
+ * checks it against the app's role only, so it never appears in a user token's `scope`.
+ *
+ * The wire format follows the OpenAPI in `openapi/paths/apps--secrets*.yaml` (C11) and the
+ * `AppSecret*` schemas in `openapi/components/components.yaml`:
+ *  - bodies and query parameters are snake_case; `created` and `expires_at` are Unix seconds;
+ *  - `find` expands the payload with `expand=payload` (comma form);
+ *  - `list` returns the QueryPager envelope `{ pager, items }`;
+ *  - `delete` returns the deleted secret with `deleted: true` (`AppSecretDeleted`, checked);
+ *  - errors use the house envelope `{ error, success: false, code }` (`error` is a list of
+ *    per-field messages on a 422 validation failure).
+ */
+
+import * as z from "zod/v4";
+import { extractSecurity, resolveGlobalSecurity } from "../../lib/security.js";
+import type { ClientSDK, RequestOptions } from "../../lib/sdks.js";
+import { pathToFunc } from "../../lib/url.js";
+import { ApiErrorResponse } from "../../models/errors/apierrorresponse.js";
+import { ResponseValidationError } from "../../models/errors/responsevalidationerror.js";
+import type { ExtensionContext } from "../context.js";
+import type { PlatformPermission } from "../manifest.js";
+import { GreenSecurityCore } from "../../core.js";
+import { createAppCoreClient, SILENT_LOGGER } from "../client/index.js";
+
+/** The platform permission every Secret Store call requires. */
+export const SECRETS_PERMISSION = "app_secrets.write" as const satisfies PlatformPermission;
+
+/**
+ * The Secret Store's 403 for an app whose role lacks {@link SECRETS_PERMISSION}. It is an
+ * `ApiErrorResponse` like every other error these helpers raise, with the server's envelope
+ * unchanged; only the class tells it apart from other 403s (for example a token that may not
+ * reach the requested user's secrets). The fix is to declare the permission in the manifest and
+ * publish a new version; an existing installation gets it once its admin accepts that version.
+ */
+export class SecretsPermissionError extends ApiErrorResponse {
+  readonly permission = SECRETS_PERMISSION;
+
+  constructor(err: ConstructorParameters<typeof ApiErrorResponse>[0], httpMeta: ConstructorParameters<typeof ApiErrorResponse>[1]) {
+    super(err, httpMeta);
+    this.name = "SecretsPermissionError";
+  }
+}
+
+/** True for the 403 raised when the app has not been granted {@link SECRETS_PERMISSION}. */
+export function isSecretsPermissionError(error: unknown): error is SecretsPermissionError {
+  return error instanceof SecretsPermissionError;
+}
+
+/**
+ * C3's envelope carries only `{ error, success, code }`, with `code` the HTTP status, so the
+ * message is the one signal: `"This app has not been granted app_secrets.write."`.
+ */
+function isMissingPermission(status: number, message: string): boolean {
+  return status === 403 && message.includes(`not been granted ${SECRETS_PERMISSION}`);
+}
+
+/** C3 limits, checked before the request is sent. */
+export const SECRET_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,100}$/;
+export const SECRET_PAYLOAD_MAX_BYTES = 8 * 1024;
+export const SECRET_MAX_LIFETIME_YEARS = 100;
+export const SECRETS_MAX_ITEMS_PER_PAGE = 100;
+export const SECRET_SORT_FIELDS = ["name", "created", "expires_at"] as const;
+export type SecretSortField = (typeof SECRET_SORT_FIELDS)[number];
+
+export type SecretScope =
+  | { type: "installation" }
+  /**
+   * `userId` may be left out with an app user token (it means the token's own user). With an
+   * installation or service-account token it is required for a `user` scope.
+   */
+  | { type: "user"; userId?: number };
+
+export interface AppSecret {
+  id: number;
+  object: "app.secret";
+  name: string;
+  scope: SecretScope;
+  created: Date;
+  /** `null` when the secret does not expire. */
+  expiresAt: Date | null;
+  /** Present only on `find` with the payload expanded (the default). */
+  payload?: string;
+}
+
+/**
+ * The result of `delete` (C11's `AppSecretDeleted`): the secret as it was just before it was
+ * deleted, without its payload, and `deleted: true`. A response without `deleted: true` is
+ * rejected, so resolving means the server confirmed the deletion.
+ */
+export type DeletedAppSecret = Omit<AppSecret, "payload"> & { deleted: true };
+
+/** QueryPager metadata of a `list` page. */
+export interface SecretsPager {
+  page?: number;
+  itemsPerPage?: number;
+  itemCount?: number;
+  sort?: string;
+  desc?: boolean;
+}
+
+export interface SecretsPage {
+  pager: SecretsPager;
+  items: AppSecret[];
+}
+
+/** A client from `createAppClient` / `createAppCoreClient`, or a view's context (uses the user token). */
+export type SecretsTarget = ClientSDK | ExtensionContext;
+
+/**
+ * Every operation takes an optional `activationId`. It is required when calling with the app
+ * service account's permanent token; with an app token it may be left out, and if given it
+ * must be the token's own activation (`403` otherwise).
+ */
+interface ActivationInput {
+  activationId?: number;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Response schemas (zod v4). Loose objects: new server fields must not break old apps.
+
+const unixSeconds = z.number().int();
+
+const wireScopeSchema = z.looseObject({
+  type: z.enum(["installation", "user"]),
+  user_id: z.number().int().nullish(),
+});
+
+const wireSecretSchema = z.looseObject({
+  id: z.number().int(),
+  object: z.literal("app.secret"),
+  name: z.string(),
+  scope: wireScopeSchema,
+  created: unixSeconds,
+  expires_at: unixSeconds.nullish(),
+  payload: z.string().nullish(),
+});
+
+/** `AppSecretDeleted`: the secret's fields (never a payload) with `deleted: true` required. */
+const wireDeletedSchema = z.looseObject({
+  ...wireSecretSchema.shape,
+  deleted: z.literal(true),
+});
+
+const wirePagerSchema = z.looseObject({
+  page: z.number().int().optional(),
+  items_per_page: z.number().int().optional(),
+  item_count: z.number().int().optional(),
+  sort: z.string().optional(),
+  desc: z.union([z.boolean(), z.number(), z.string()]).optional(),
+});
+
+const wireListSchema = z.looseObject({
+  pager: wirePagerSchema,
+  items: z.array(wireSecretSchema),
+});
+
+const errorBodySchema = z.looseObject({
+  error: z.union([z.string(), z.array(z.unknown()), z.record(z.string(), z.unknown())]),
+  success: z.boolean().optional(),
+  code: z.number().nullish(),
+});
+
+type WireSecret = z.infer<typeof wireSecretSchema>;
+type WirePager = z.infer<typeof wirePagerSchema>;
+
+const fromUnixSeconds = (seconds: number) => new Date(seconds * 1000);
+
+function fromWire(secret: WireSecret): AppSecret {
+  const scope: SecretScope = secret.scope.type === "user"
+    ? (typeof secret.scope.user_id === "number" ? { type: "user", userId: secret.scope.user_id } : { type: "user" })
+    : { type: "installation" };
+
+  const result: AppSecret = {
+    id: secret.id,
+    object: secret.object,
+    name: secret.name,
+    scope,
+    created: fromUnixSeconds(secret.created),
+    expiresAt: typeof secret.expires_at === "number" ? fromUnixSeconds(secret.expires_at) : null,
+  };
+  if (typeof secret.payload === "string") result.payload = secret.payload;
+  return result;
+}
+
+function deletedFromWire(secret: z.infer<typeof wireDeletedSchema>): DeletedAppSecret {
+  const { payload: _payload, ...rest } = fromWire(secret);
+  return { ...rest, deleted: true };
+}
+
+function pagerFromWire(pager: WirePager): SecretsPager {
+  const result: SecretsPager = {};
+  if (pager.page !== undefined) result.page = pager.page;
+  if (pager.items_per_page !== undefined) result.itemsPerPage = pager.items_per_page;
+  if (pager.item_count !== undefined) result.itemCount = pager.item_count;
+  if (pager.sort !== undefined) result.sort = pager.sort;
+  if (pager.desc !== undefined) result.desc = pager.desc === true || pager.desc === 1 || pager.desc === "1" || pager.desc === "true";
+  return result;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Validation
+
+function checkName(name: unknown): string {
+  if (typeof name !== "string" || !SECRET_NAME_PATTERN.test(name)) {
+    throw new TypeError("Secret names are 1-100 characters of A-Z, a-z, 0-9, '_', '.' or '-'");
+  }
+  return name;
+}
+
+function checkPositiveInt(value: number, what: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${what} must be a positive integer`);
+  return value;
+}
+
+function wireScope(scope: SecretScope | undefined): { type: "installation" } | { type: "user"; user_id?: number } {
+  if (!scope || (scope.type !== "installation" && scope.type !== "user")) {
+    throw new TypeError('A secret scope is required: { type: "installation" } or { type: "user", userId? }');
+  }
+  if (scope.type === "installation") {
+    if ("userId" in scope && (scope as { userId?: unknown }).userId !== undefined) {
+      throw new TypeError("An installation scope cannot name a user");
+    }
+    return { type: "installation" };
+  }
+  if (scope.userId === undefined) return { type: "user" };
+  return { type: "user", user_id: checkPositiveInt(scope.userId, "scope.userId") };
+}
+
+function scopeQuery(params: URLSearchParams, scope: SecretScope | undefined): void {
+  const wire = wireScope(scope);
+  params.set("scope[type]", wire.type);
+  if ("user_id" in wire && wire.user_id !== undefined) params.set("scope[user_id]", String(wire.user_id));
+}
+
+function activationQuery(params: URLSearchParams, input: ActivationInput): void {
+  if (input.activationId !== undefined) params.set("activation_id", String(checkPositiveInt(input.activationId, "activationId")));
+}
+
+function activationBody(body: Record<string, unknown>, input: ActivationInput): void {
+  if (input.activationId !== undefined) body["activation_id"] = checkPositiveInt(input.activationId, "activationId");
+}
+
+/** A Date or epoch milliseconds, in the future and under 100 years away, as Unix seconds. */
+function toExpiry(value: Date | number): number {
+  const ms = value instanceof Date ? value.getTime() : value;
+  if (typeof ms !== "number" || !Number.isFinite(ms)) throw new TypeError("expiresAt must be a Date or epoch milliseconds");
+  if (ms <= Date.now()) throw new RangeError("expiresAt must be in the future");
+  // Rounded up, so an expiry a few hundred milliseconds away is still in the future server-side.
+  const seconds = Math.ceil(ms / 1000);
+  const limit = new Date();
+  limit.setFullYear(limit.getFullYear() + SECRET_MAX_LIFETIME_YEARS);
+  if (seconds * 1000 >= limit.getTime()) throw new RangeError(`expiresAt must be less than ${SECRET_MAX_LIFETIME_YEARS} years away`);
+  return seconds;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Request plumbing (the `admin-funcs/doAdmin.ts` pattern, but on the caller's client)
+
+/** Silent copies of caller-built clients, one per client. */
+const SILENT_CLIENTS = new WeakMap<ClientSDK, ClientSDK>();
+
+/**
+ * The client a helper sends through. A client from `createAppClient` is already silent. Any
+ * other client (one built with `new GreenSecurityCore({ debugLogger })`, or while
+ * `GREEN_SECURITY_DEBUG` is set) would log the bearer token and the plaintext payloads of
+ * `set` and `find`, so the helpers send through a copy of it with the same options, hooks and
+ * HTTP client, but a silent logger.
+ */
+function resolveClient(target: SecretsTarget): ClientSDK {
+  if (isExtensionContext(target)) return createAppCoreClient(target, { as: "user" });
+  if (target._options.debugLogger === SILENT_LOGGER) return target;
+  let silent = SILENT_CLIENTS.get(target);
+  if (!silent) {
+    silent = new GreenSecurityCore({ ...target._options, debugLogger: SILENT_LOGGER });
+    SILENT_CLIENTS.set(target, silent);
+  }
+  return silent;
+}
+
+function isExtensionContext(value: SecretsTarget): value is ExtensionContext {
+  return typeof value === "object" && value !== null && "protocolVersion" in value && "auth" in value;
+}
+
+function errorMessage(error: unknown, status: number): string {
+  if (typeof error === "string" && error) return error;
+  if (error !== undefined && error !== null) {
+    try {
+      return JSON.stringify(error);
+    } catch {
+      // fall through
+    }
+  }
+  return `HTTP ${status}`;
+}
+
+async function send<T>(
+  target: SecretsTarget,
+  operation: string,
+  method: "GET" | "POST",
+  path: string,
+  schema: z.ZodType<T>,
+  init: { query?: URLSearchParams; body?: unknown },
+  options?: RequestOptions,
+): Promise<T> {
+  const client = resolveClient(target);
+
+  // Bearer only: app tokens are refused as `?token=` query params.
+  const securityInput = await extractSecurity(client._options.security);
+  const security = resolveGlobalSecurity(securityInput, [1]);
+
+  const retryConfig = options?.retries || client._options.retryConfig || { strategy: "none" as const };
+  const retryCodes = options?.retryCodes || ["429", "500", "502", "503", "504"];
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: `appSecrets.${operation}`,
+    oAuth2Scopes: null,
+    resolvedSecurity: security,
+    securitySource: client._options.security,
+    retryConfig,
+  };
+
+  const headers = new Headers({ Accept: "application/json" });
+  if (init.body !== undefined) headers.set("Content-Type", "application/json");
+
+  const query = init.query?.toString();
+  const built = client._createRequest(context, {
+    security,
+    method,
+    baseURL: options?.serverURL,
+    path: pathToFunc(path)(),
+    headers,
+    ...(query ? { query } : {}),
+    body: init.body === undefined ? null : JSON.stringify(init.body),
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!built.ok) throw built.error;
+  const request = built.value;
+
+  const done = await client._do(request, {
+    context,
+    isErrorStatusCode: (status: number) => status >= 400,
+    retryConfig,
+    retryCodes,
+  });
+  if (!done.ok) throw done.error;
+  const response = done.value;
+  const body = await response.text();
+
+  if (!response.ok) {
+    const parsedError = errorBodySchema.safeParse(safeJson(body));
+    const data = parsedError.success
+      ? {
+        error: errorMessage(parsedError.data.error, response.status),
+        ...(parsedError.data.success !== undefined ? { success: parsedError.data.success } : {}),
+        ...(parsedError.data.code != null ? { code: parsedError.data.code } : {}),
+      }
+      : { error: `HTTP ${response.status}` };
+    const httpMeta = { response, request, body };
+    if (isMissingPermission(response.status, data.error)) throw new SecretsPermissionError(data, httpMeta);
+    throw new ApiErrorResponse(data, httpMeta);
+  }
+
+  const json = safeJson(body);
+  const parsed = schema.safeParse(json);
+  if (!parsed.success) {
+    throw new ResponseValidationError(`Unexpected ${operation} response: ${z.prettifyError(parsed.error)}`, {
+      response,
+      request,
+      body,
+      cause: parsed.error,
+      rawValue: json,
+      rawMessage: "Response validation failed",
+    });
+  }
+  return parsed.data;
+}
+
+function safeJson(text: string): unknown {
+  if (!text) return null;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Public API
+
+export interface SetSecretInput extends ActivationInput {
+  name: string;
+  /** Not blank, at most 8192 bytes once UTF-8 encoded. */
+  payload: string;
+  scope: SecretScope;
+  /** Optional expiry (a Date or epoch milliseconds): in the future, under 100 years away. */
+  expiresAt?: Date | number;
+}
+
+/**
+ * Creates or replaces a secret (upsert by name within the scope). The payload is not echoed back.
+ * Needs `app_secrets.write` (else a {@link SecretsPermissionError}).
+ */
+async function set(target: SecretsTarget, input: SetSecretInput, options?: RequestOptions): Promise<AppSecret> {
+  const name = checkName(input.name);
+  if (typeof input.payload !== "string" || input.payload.trim() === "") throw new TypeError("payload must be a non-blank string");
+  if (new TextEncoder().encode(input.payload).length > SECRET_PAYLOAD_MAX_BYTES) {
+    throw new RangeError(`Secret payloads are limited to ${SECRET_PAYLOAD_MAX_BYTES} bytes`);
+  }
+
+  const body: Record<string, unknown> = { name, payload: input.payload, scope: wireScope(input.scope) };
+  if (input.expiresAt !== undefined) body["expires_at"] = toExpiry(input.expiresAt);
+  activationBody(body, input);
+
+  return fromWire(await send(target, "set", "POST", "/apps/secrets", wireSecretSchema, { body }, options));
+}
+
+export interface FindSecretInput extends ActivationInput {
+  name: string;
+  scope: SecretScope;
+  /** Include the decrypted payload (`expand=payload`). Defaults to true. */
+  expandPayload?: boolean;
+}
+
+/**
+ * Reads one secret. Rejects with an `ApiErrorResponse` (404) when it does not exist.
+ * Needs `app_secrets.write` (else a {@link SecretsPermissionError}).
+ */
+async function find(target: SecretsTarget, input: FindSecretInput, options?: RequestOptions): Promise<AppSecret> {
+  const query = new URLSearchParams();
+  query.set("name", checkName(input.name));
+  scopeQuery(query, input.scope);
+  activationQuery(query, input);
+  if (input.expandPayload !== false) query.set("expand", "payload");
+
+  return fromWire(await send(target, "find", "GET", "/apps/secrets/find", wireSecretSchema, { query }, options));
+}
+
+export interface DeleteSecretInput extends ActivationInput {
+  name: string;
+  scope: SecretScope;
+}
+
+/**
+ * Deletes a secret and resolves with it (`deleted: true`). Rejects with a 404 when it does not
+ * exist, and with a `ResponseValidationError` if a 200 does not confirm `deleted: true`.
+ * Needs `app_secrets.write` (else a {@link SecretsPermissionError}).
+ */
+async function deleteSecret(target: SecretsTarget, input: DeleteSecretInput, options?: RequestOptions): Promise<DeletedAppSecret> {
+  const body: Record<string, unknown> = { name: checkName(input.name), scope: wireScope(input.scope) };
+  activationBody(body, input);
+  return deletedFromWire(await send(target, "delete", "POST", "/apps/secrets/delete", wireDeletedSchema, { body }, options));
+}
+
+export interface ListSecretsInput extends ActivationInput {
+  scope: SecretScope;
+  /** 1-based page. */
+  page?: number;
+  /** 1–100; the server defaults to 25. */
+  itemsPerPage?: number;
+  /** Defaults to `name`. */
+  sort?: SecretSortField;
+  desc?: boolean;
+}
+
+/**
+ * Lists one page of secrets in a scope. Payloads are never included; expired secrets are not listed.
+ * Needs `app_secrets.write` (else a {@link SecretsPermissionError}).
+ */
+async function list(target: SecretsTarget, input: ListSecretsInput, options?: RequestOptions): Promise<SecretsPage> {
+  const query = new URLSearchParams();
+  scopeQuery(query, input.scope);
+  activationQuery(query, input);
+  if (input.page !== undefined) query.set("page", String(checkPositiveInt(input.page, "page")));
+  if (input.itemsPerPage !== undefined) {
+    if (!Number.isInteger(input.itemsPerPage) || input.itemsPerPage < 1 || input.itemsPerPage > SECRETS_MAX_ITEMS_PER_PAGE) {
+      throw new RangeError(`itemsPerPage must be an integer from 1 to ${SECRETS_MAX_ITEMS_PER_PAGE}`);
+    }
+    query.set("items_per_page", String(input.itemsPerPage));
+  }
+  if (input.sort !== undefined) {
+    if (!SECRET_SORT_FIELDS.includes(input.sort)) throw new TypeError(`sort must be one of: ${SECRET_SORT_FIELDS.join(", ")}`);
+    query.set("sort", input.sort);
+  }
+  if (input.desc !== undefined) query.set("desc", String(input.desc));
+
+  const page = await send(target, "list", "GET", "/apps/secrets", wireListSchema, { query }, options);
+  return { pager: pagerFromWire(page.pager), items: page.items.map(fromWire) };
+}
+
+/**
+ * The Secret Store helpers. Each one requires the app's manifest to declare, and its installation
+ * to grant, the `app_secrets.write` platform permission; see {@link SecretsPermissionError}.
+ */
+export const secrets = { set, find, delete: deleteSecret, list } as const;

package/src/apps/secrets.ts

@@ -0,0 +1,8 @@
+/*
+ * Hand-written (not generated by Speakeasy). Entry point for
+ * `@greensecurity/javascript-sdk/apps/secrets` (third-party app developer kit, C10). The package
+ * `exports` map resolves `./apps/<name>` to `src/apps/<name>.ts`, so each kit folder gets
+ * a one-line entry file next to it.
+ */
+
+export * from "./secrets/index.js";

package/src/apps/surfaces.ts

@@ -0,0 +1,158 @@
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md. Host (web-mobile-client) and SDK both import from here.
+ */
+
+export type Portal = "vendor" | "company" | "facility" | "system";
+
+export type SurfaceKind =
+  | "navigation"
+  | "drawer.default"
+  | "overview"
+  | "list"
+  | "list.row_action"
+  | "detail"
+  | "detail.tabs"
+  | "settings";
+
+/**
+ * The kind of record a surface is showing. These match the public API resource each one is
+ * read through (`/vendors`, `/vendors/credentials`, `/facilities`, `/companies`,
+ * `/vendor-scans`, `/invoices`, `/events`). `visitor` and `contact` belong to Wave 2 surfaces
+ * and have no public read endpoint yet.
+ */
+export type ObjectType =
+  | "vendor"
+  | "vendor_credential"
+  | "facility"
+  | "company"
+  | "vendor_scan"
+  | "invoice"
+  | "event"
+  | "visitor"
+  | "contact";
+
+export interface SurfaceDef {
+  readonly id: string;
+  readonly portal: Portal | null;
+  readonly kind: SurfaceKind;
+  readonly objectType: ObjectType | null;
+  /**
+   * Expo Router path of the screen the surface lives on. For a surface with no portal, `[portal]`
+   * stands for the viewer's current portal: `settings` is `/company/apps/42/settings` for a
+   * company user.
+   */
+  readonly route: string;
+  /**
+   * Search param the screen reads the record id from. `null` when the surface has no record, or
+   * when the screen decodes its id from something else (the invoice screens take a JSON
+   * `params` value) and the host has to map it itself.
+   */
+  readonly idParam: string | null;
+  /** Wave 1 surfaces are rendered by the host; Wave 2 ids are reserved and accepted in manifests. */
+  readonly wave: 1 | 2;
+}
+
+type Entry = [id: string, kind: SurfaceKind, objectType: ObjectType | null, route: string, idParam: string | null];
+
+/** Expands a list surface into the surface itself and its row-action surface. */
+function list(portal: Portal, entity: string, objectType: ObjectType, route: string): Entry[] {
+  return [
+    [`gs.${portal}.${entity}.list`, "list", null, route, null],
+    [`gs.${portal}.${entity}.list.row_action`, "list.row_action", objectType, route, null],
+  ];
+}
+
+function portalShell(portal: Portal): Entry[] {
+  return [
+    [`gs.${portal}.navigation`, "navigation", null, `/${portal}`, null],
+    [`gs.${portal}.drawer.default`, "drawer.default", null, `/${portal}`, null],
+    [`gs.${portal}.dashboard.overview`, "overview", null, `/${portal}/dashboard`, null],
+  ];
+}
+
+const COMPANY: Entry[] = [
+  ...portalShell("company"),
+  ...list("company", "vendor", "vendor", "/company/vendors"),
+  ["gs.company.vendor.detail", "detail", "vendor", "/company/vendordetails", "vendorId"],
+  ["gs.company.vendor.detail.tabs", "detail.tabs", "vendor", "/company/vendordetails", "vendorId"],
+  ...list("company", "vendor_credential", "vendor_credential", "/company/credentials"),
+  ["gs.company.vendor_credential.detail", "detail", "vendor_credential", "/company/credentials/[id]", "id"],
+  ...list("company", "facility", "facility", "/company/facilities"),
+  ["gs.company.facility.detail", "detail", "facility", "/company/facilities/details", "id"],
+  ...list("company", "vendor_scan", "vendor_scan", "/company/scans"),
+  ["gs.company.vendor_scan.detail", "detail", "vendor_scan", "/company/scans/details", "id"],
+  ...list("company", "invoice", "invoice", "/company/invoices"),
+  ["gs.company.invoice.detail", "detail", "invoice", "/company/invoices/invoicedetails", null],
+  ["gs.company.account.overview", "overview", "company", "/company/account", null],
+  ["gs.company.account.detail.tabs", "detail.tabs", "company", "/company/account", null],
+];
+
+const VENDOR: Entry[] = [
+  ...portalShell("vendor"),
+  ...list("vendor", "vendor_credential", "vendor_credential", "/vendor/credentials"),
+  ["gs.vendor.vendor_credential.detail", "detail", "vendor_credential", "/vendor/credentials/[id]", "id"],
+  ...list("vendor", "facility", "facility", "/vendor/facilities"),
+  ["gs.vendor.facility.detail", "detail", "facility", "/vendor/facilities/details", "facilityId"],
+  ...list("vendor", "event", "event", "/vendor/calendar"),
+  ...list("vendor", "invoice", "invoice", "/vendor/account/invoices"),
+  ["gs.vendor.invoice.detail", "detail", "invoice", "/vendor/account/invoicedetails", null],
+  ["gs.vendor.account.overview", "overview", "vendor", "/vendor/account", null],
+  ["gs.vendor.account.detail.tabs", "detail.tabs", "vendor", "/vendor/account", null],
+  ["gs.vendor.checkin.overview", "overview", null, "/vendor/mobilecheckin", null],
+];
+
+/** Facility and system portals share one screen set; both are reserved for Wave 2. */
+function staffPortal(portal: "facility" | "system"): Entry[] {
+  return [
+    ...portalShell(portal),
+    ...list(portal, "company", "company", `/${portal}/companies`),
+    [`gs.${portal}.company.detail`, "detail", "company", `/${portal}/companies/[id]`, "id"],
+    ...list(portal, "vendor", "vendor", `/${portal}/vendors`),
+    ...list(portal, "visitor", "visitor", `/${portal}/visitors`),
+    ...list(portal, "contact", "contact", `/${portal}/contacts`),
+    ...list(portal, "vendor_credential", "vendor_credential", `/${portal}/credentials`),
+    ...list(portal, "event", "event", `/${portal}/calendar`),
+    [`gs.${portal}.report.overview`, "overview", null, `/${portal}/reports`, null],
+  ];
+}
+
+function define(portal: Portal | null, wave: 1 | 2, entries: Entry[]): SurfaceDef[] {
+  return entries.map(([id, kind, objectType, route, idParam]) => ({ id, portal, kind, objectType, route, idParam, wave }));
+}
+
+export const SURFACES: readonly SurfaceDef[] = Object.freeze([
+  ...define("company", 1, COMPANY),
+  ...define("vendor", 1, VENDOR),
+  ...define("facility", 2, staffPortal("facility")),
+  ...define("system", 2, staffPortal("system")),
+  // The app's own settings page. Every portal has one, so the route names the portal as a segment.
+  ...define(null, 1, [["settings", "settings", null, "/[portal]/apps/[appId]/settings", "appId"]]),
+]);
+
+/**
+ * A surface identifier. This is deliberately a plain `string`: the catalog is data-driven, so the
+ * compiler cannot tell a real id from a typo. Validity is a runtime property — check untrusted or
+ * hand-written ids with {@link isSurfaceId}, as `isRouteDescriptor` and the manifest schema do.
+ */
+export type SurfaceId = string;
+
+const SURFACES_BY_ID: ReadonlyMap<string, SurfaceDef> = new Map(SURFACES.map((s) => [s.id, s]));
+
+export function isSurfaceId(value: unknown): value is SurfaceId {
+  return typeof value === "string" && SURFACES_BY_ID.has(value);
+}
+
+export function getSurface(id: string): SurfaceDef | undefined {
+  return SURFACES_BY_ID.get(id);
+}
+
+/** The fallback surface a portal resolves to when an app has no view for the exact surface. */
+export function drawerDefaultFor(portal: Portal): SurfaceId {
+  return `gs.${portal}.drawer.default`;
+}
+
+/** Surfaces the host renders for a portal in the given wave (and earlier waves). */
+export function surfacesForPortal(portal: Portal, wave: 1 | 2 = 1): SurfaceDef[] {
+  return SURFACES.filter((s) => s.portal === portal && s.wave <= wave);
+}