@greensecurity/javascript-sdk 0.46.0-beta.1 → 0.46.0-beta.11

package/dist/commonjs/apps/review.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The thresholds and lists the review applies to a submission's added permissions.
+ *
+ * - `purpose_min_chars`: the shortest `purpose` accepted for an added permission, after trimming.
+ * - `justification_min_chars`: the shortest `justification` accepted for an added sensitive
+ *   permission, after trimming.
+ * - `read_only_actions`: the permission actions that only read. Every other action (`add`, `edit`,
+ *   `delete`, `write`, and any added later) writes, and a permission that writes is sensitive.
+ * - `pii_resources`: the resources whose records identify people or describe them (names, contact
+ *   details, credentials, background checks, visits, payment details). Reading one is sensitive.
+ */
+export declare const REVIEW_RULES: Readonly<{
+    readonly purpose_min_chars: 30;
+    readonly justification_min_chars: 40;
+    readonly read_only_actions: readonly ["view", "search"];
+    readonly pii_resources: readonly ["background_checks", "communications", "company_managers", "contacts", "credentials", "criminal_history", "events", "invoices", "mobile_devices", "payment_profiles", "users", "vendor_credentials", "vendor_scans", "vendor_transactions", "vendors", "visitor_checkins", "visitors", "watchlist_entries"];
+}>;
+/**
+ * Whether a `resource.action` permission is sensitive: it writes (any action that is not read-only)
+ * or it reads a resource about people. A sensitive permission added by a submission needs a
+ * `justification` as well as a `purpose`, and holds the submission for a Green Security admin.
+ */
+export declare function isSensitivePermission(permission: string): boolean;
+/** Why a host is on the denylist. */
+export type CspDenylistCategory = "tunnel" | "pastebin" | "url_shortener" | "raw_code_host" | "dynamic_dns";
+export interface CspDenylistEntry {
+    /** A registrable domain or host. It matches itself and every name under it. */
+    domain: string;
+    category: CspDenylistCategory;
+}
+/**
+ * Hosts a submission may never add to `connect_src` or `image_src`, nor serve its bundle from. Each
+ * lets anybody publish content, or point a name at any address, without owning a domain, so an app
+ * that could reach one could reach anything:
+ *
+ * - `tunnel`: expose a local server under a shared domain;
+ * - `pastebin`: host arbitrary text, including code and exfiltrated data;
+ * - `url_shortener`: redirect to a destination the review never saw;
+ * - `raw_code_host`: serve files straight out of anybody's repository or gist;
+ * - `dynamic_dns`: hand out names under a shared domain, including the wildcard DNS services that
+ *   resolve a name such as `10.0.0.1.nip.io` to the IP address inside it.
+ */
+export declare const CSP_DENYLIST: readonly CspDenylistEntry[];
+/**
+ * The denylist entry a host falls under, or `undefined` when it is on none: the host is the entry's
+ * domain or a name under it (`abc.trycloudflare.com`). Case and a trailing dot are ignored.
+ */
+export declare function cspDenylistEntry(host: string): CspDenylistEntry | undefined;
+/** One problem the review would find with an added permission, as the catalog reports it. */
+export interface PermissionReviewIssue {
+    code: "purpose_too_short" | "purpose_is_permission_name" | "purpose_repeated" | "justification_required" | "justification_too_short" | "justification_repeats_purpose";
+    path: string;
+    message: string;
+}
+/**
+ * The justification rules the review applies to the permissions a submission adds, so the CLI can
+ * report them before upload. `added` names the permissions that are new since the last accepted
+ * version; the rest are not checked. Every entry's `purpose` counts when looking for repeats.
+ */
+export declare function permissionReviewIssues(permissions: ReadonlyArray<{
+    permission: string;
+    purpose: string;
+    justification?: string | undefined;
+}>, added: ReadonlySet<string>): PermissionReviewIssue[];
+//# sourceMappingURL=review.d.ts.map

package/dist/commonjs/apps/review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../../src/apps/review.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY;;;;;EAwBd,CAAC;AAKZ;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAOjE;AAED,qCAAqC;AACrC,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,eAAe,GAAG,eAAe,GAAG,aAAa,CAAC;AAE5G,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,mBAAmB,CAAC;CAC/B;AAMD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,gBAAgB,EA6FlD,CAAC;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAG3E;AAED,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,mBAAmB,GAAG,4BAA4B,GAAG,kBAAkB,GAAG,wBAAwB,GACpG,yBAAyB,GAAG,+BAA+B,CAAC;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,aAAa,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC,EACvG,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GACzB,qBAAqB,EAAE,CAqCzB"}

package/dist/commonjs/apps/review.js

@@ -0,0 +1,231 @@
+"use strict";
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md (C18).
+ *
+ * The automated review every catalog submission goes through, as data the server and the CLI
+ * share: which permissions count as sensitive, how long a `purpose` and a `justification` must be,
+ * and which CSP hosts are never accepted. The server reads the JSON these are written to
+ * (`shared/app-platform/review-rules.json` and `csp-denylist.json`); `src/__tests__/apps` keeps the
+ * files in step. Deliberately dependency-free (no zod), like `url.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CSP_DENYLIST = exports.REVIEW_RULES = void 0;
+exports.isSensitivePermission = isSensitivePermission;
+exports.cspDenylistEntry = cspDenylistEntry;
+exports.permissionReviewIssues = permissionReviewIssues;
+/**
+ * The thresholds and lists the review applies to a submission's added permissions.
+ *
+ * - `purpose_min_chars`: the shortest `purpose` accepted for an added permission, after trimming.
+ * - `justification_min_chars`: the shortest `justification` accepted for an added sensitive
+ *   permission, after trimming.
+ * - `read_only_actions`: the permission actions that only read. Every other action (`add`, `edit`,
+ *   `delete`, `write`, and any added later) writes, and a permission that writes is sensitive.
+ * - `pii_resources`: the resources whose records identify people or describe them (names, contact
+ *   details, credentials, background checks, visits, payment details). Reading one is sensitive.
+ */
+exports.REVIEW_RULES = Object.freeze({
+    purpose_min_chars: 30,
+    justification_min_chars: 40,
+    read_only_actions: Object.freeze(["view", "search"]),
+    pii_resources: Object.freeze([
+        "background_checks",
+        "communications",
+        "company_managers",
+        "contacts",
+        "credentials",
+        "criminal_history",
+        "events",
+        "invoices",
+        "mobile_devices",
+        "payment_profiles",
+        "users",
+        "vendor_credentials",
+        "vendor_scans",
+        "vendor_transactions",
+        "vendors",
+        "visitor_checkins",
+        "visitors",
+        "watchlist_entries",
+    ]),
+});
+const READ_ONLY_ACTIONS = new Set(exports.REVIEW_RULES.read_only_actions);
+const PII_RESOURCES = new Set(exports.REVIEW_RULES.pii_resources);
+/**
+ * Whether a `resource.action` permission is sensitive: it writes (any action that is not read-only)
+ * or it reads a resource about people. A sensitive permission added by a submission needs a
+ * `justification` as well as a `purpose`, and holds the submission for a Green Security admin.
+ */
+function isSensitivePermission(permission) {
+    const dot = permission.indexOf(".");
+    if (dot <= 0 || dot === permission.length - 1)
+        return true;
+    const resource = permission.slice(0, dot);
+    const action = permission.slice(dot + 1);
+    return !READ_ONLY_ACTIONS.has(action) || PII_RESOURCES.has(resource);
+}
+function entries(category, domains) {
+    return domains.map((domain) => ({ domain, category }));
+}
+/**
+ * Hosts a submission may never add to `connect_src` or `image_src`, nor serve its bundle from. Each
+ * lets anybody publish content, or point a name at any address, without owning a domain, so an app
+ * that could reach one could reach anything:
+ *
+ * - `tunnel`: expose a local server under a shared domain;
+ * - `pastebin`: host arbitrary text, including code and exfiltrated data;
+ * - `url_shortener`: redirect to a destination the review never saw;
+ * - `raw_code_host`: serve files straight out of anybody's repository or gist;
+ * - `dynamic_dns`: hand out names under a shared domain, including the wildcard DNS services that
+ *   resolve a name such as `10.0.0.1.nip.io` to the IP address inside it.
+ */
+exports.CSP_DENYLIST = Object.freeze([
+    ...entries("tunnel", [
+        "trycloudflare.com",
+        "ngrok.io",
+        "ngrok.app",
+        "ngrok.dev",
+        "ngrok-free.app",
+        "ngrok-free.dev",
+        "loca.lt",
+        "localtunnel.me",
+        "localhost.run",
+        "lhr.life",
+        "serveo.net",
+        "serveousercontent.com",
+        "pagekite.me",
+        "tunnelto.dev",
+        "bore.pub",
+        "loclx.io",
+        "localxpose.io",
+        "pinggy.io",
+        "pinggy.link",
+        "devtunnels.ms",
+        "tunnelmole.net",
+        "localtonet.com",
+        "zrok.io",
+        "sharedwithexpose.com",
+    ]),
+    ...entries("pastebin", [
+        "pastebin.com",
+        "paste.ee",
+        "hastebin.com",
+        "rentry.co",
+        "dpaste.com",
+        "dpaste.org",
+        "paste.rs",
+        "termbin.com",
+        "controlc.com",
+        "justpaste.it",
+        "privatebin.net",
+        "pastes.dev",
+        "ix.io",
+        "sprunge.us",
+    ]),
+    ...entries("url_shortener", [
+        "bit.ly",
+        "tinyurl.com",
+        "t.co",
+        "goo.gl",
+        "ow.ly",
+        "is.gd",
+        "v.gd",
+        "buff.ly",
+        "rebrand.ly",
+        "cutt.ly",
+        "shorturl.at",
+        "rb.gy",
+        "tiny.cc",
+        "t.ly",
+        "bl.ink",
+    ]),
+    ...entries("raw_code_host", [
+        "raw.githubusercontent.com",
+        "gist.githubusercontent.com",
+        "gist.github.com",
+        "raw.githack.com",
+        "rawcdn.githack.com",
+        "cdn.statically.io",
+    ]),
+    ...entries("dynamic_dns", [
+        "duckdns.org",
+        "no-ip.com",
+        "no-ip.org",
+        "ddns.net",
+        "hopto.org",
+        "zapto.org",
+        "sytes.net",
+        "dynu.com",
+        "dynu.net",
+        "dyndns.org",
+        "dynalias.com",
+        "changeip.com",
+        "afraid.org",
+        "mooo.com",
+        "dedyn.io",
+        "nsupdate.info",
+        "ydns.eu",
+        "dynv6.net",
+        "nip.io",
+        "sslip.io",
+        "xip.io",
+        "traefik.me",
+        "localtest.me",
+    ]),
+]);
+/**
+ * The denylist entry a host falls under, or `undefined` when it is on none: the host is the entry's
+ * domain or a name under it (`abc.trycloudflare.com`). Case and a trailing dot are ignored.
+ */
+function cspDenylistEntry(host) {
+    const name = host.toLowerCase().replace(/\.$/, "");
+    return exports.CSP_DENYLIST.find((entry) => name === entry.domain || name.endsWith(`.${entry.domain}`));
+}
+/** Lower case, with every run of non-alphanumerics collapsed to one space: how two texts are compared. */
+function normalizedText(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+/**
+ * The justification rules the review applies to the permissions a submission adds, so the CLI can
+ * report them before upload. `added` names the permissions that are new since the last accepted
+ * version; the rest are not checked. Every entry's `purpose` counts when looking for repeats.
+ */
+function permissionReviewIssues(permissions, added) {
+    const issues = [];
+    const purposeCounts = new Map();
+    for (const entry of permissions) {
+        const key = normalizedText(entry.purpose);
+        purposeCounts.set(key, (purposeCounts.get(key) ?? 0) + 1);
+    }
+    permissions.forEach((entry, index) => {
+        if (!added.has(entry.permission))
+            return;
+        const path = `permissions.${index}`;
+        const purpose = normalizedText(entry.purpose);
+        const [resource = "", action = ""] = entry.permission.split(".");
+        if (entry.purpose.trim().length < exports.REVIEW_RULES.purpose_min_chars) {
+            issues.push({ code: "purpose_too_short", path: `${path}.purpose`, message: `must be at least ${exports.REVIEW_RULES.purpose_min_chars} characters and say what the app does with ${entry.permission}` });
+        }
+        if ([normalizedText(entry.permission), normalizedText(resource), normalizedText(`${action} ${resource}`)].includes(purpose)) {
+            issues.push({ code: "purpose_is_permission_name", path: `${path}.purpose`, message: "must explain what the app does with the permission, not repeat its name" });
+        }
+        if ((purposeCounts.get(purpose) ?? 0) > 1) {
+            issues.push({ code: "purpose_repeated", path: `${path}.purpose`, message: "must be written for this permission; another permission has the same purpose" });
+        }
+        if (!isSensitivePermission(entry.permission))
+            return;
+        const justification = entry.justification?.trim() ?? "";
+        if (justification.length === 0) {
+            issues.push({ code: "justification_required", path: `${path}.justification`, message: `${entry.permission} is sensitive and needs a justification explaining why the app cannot work without it` });
+        }
+        else if (justification.length < exports.REVIEW_RULES.justification_min_chars) {
+            issues.push({ code: "justification_too_short", path: `${path}.justification`, message: `must be at least ${exports.REVIEW_RULES.justification_min_chars} characters` });
+        }
+        else if (normalizedText(justification) === purpose) {
+            issues.push({ code: "justification_repeats_purpose", path: `${path}.justification`, message: "must say why the permission is needed, not repeat its purpose" });
+        }
+    });
+    return issues;
+}
+//# sourceMappingURL=review.js.map

package/dist/commonjs/apps/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../../../src/apps/review.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AA+CH,sDAOC;AA8HD,4CAGC;AAoBD,wDAwCC;AAjPD;;;;;;;;;;GAUG;AACU,QAAA,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC;IACxC,iBAAiB,EAAE,EAAE;IACrB,uBAAuB,EAAE,EAAE;IAC3B,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAU,CAAC;IAC7D,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC;QAC3B,mBAAmB;QACnB,gBAAgB;QAChB,kBAAkB;QAClB,UAAU;QACV,aAAa;QACb,kBAAkB;QAClB,QAAQ;QACR,UAAU;QACV,gBAAgB;QAChB,kBAAkB;QAClB,OAAO;QACP,oBAAoB;QACpB,cAAc;QACd,qBAAqB;QACrB,SAAS;QACT,kBAAkB;QAClB,UAAU;QACV,mBAAmB;KACX,CAAC;CACH,CAAC,CAAC;AAEZ,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC,oBAAY,CAAC,iBAAiB,CAAC,CAAC;AACvF,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,oBAAY,CAAC,aAAa,CAAC,CAAC;AAE/E;;;;GAIG;AACH,SAAgB,qBAAqB,CAAC,UAAkB;IACtD,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3D,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACzC,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACvE,CAAC;AAWD,SAAS,OAAO,CAAC,QAA6B,EAAE,OAA0B;IACxE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;GAWG;AACU,QAAA,YAAY,GAAgC,MAAM,CAAC,MAAM,CAAC;IACrE,GAAG,OAAO,CAAC,QAAQ,EAAE;QACnB,mBAAmB;QACnB,UAAU;QACV,WAAW;QACX,WAAW;QACX,gBAAgB;QAChB,gBAAgB;QAChB,SAAS;QACT,gBAAgB;QAChB,eAAe;QACf,UAAU;QACV,YAAY;QACZ,uBAAuB;QACvB,aAAa;QACb,cAAc;QACd,UAAU;QACV,UAAU;QACV,eAAe;QACf,WAAW;QACX,aAAa;QACb,eAAe;QACf,gBAAgB;QAChB,gBAAgB;QAChB,SAAS;QACT,sBAAsB;KACvB,CAAC;IACF,GAAG,OAAO,CAAC,UAAU,EAAE;QACrB,cAAc;QACd,UAAU;QACV,cAAc;QACd,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,UAAU;QACV,aAAa;QACb,cAAc;QACd,cAAc;QACd,gBAAgB;QAChB,YAAY;QACZ,OAAO;QACP,YAAY;KACb,CAAC;IACF,GAAG,OAAO,CAAC,eAAe,EAAE;QAC1B,QAAQ;QACR,aAAa;QACb,MAAM;QACN,QAAQ;QACR,OAAO;QACP,OAAO;QACP,MAAM;QACN,SAAS;QACT,YAAY;QACZ,SAAS;QACT,aAAa;QACb,OAAO;QACP,SAAS;QACT,MAAM;QACN,QAAQ;KACT,CAAC;IACF,GAAG,OAAO,CAAC,eAAe,EAAE;QAC1B,2BAA2B;QAC3B,4BAA4B;QAC5B,iBAAiB;QACjB,iBAAiB;QACjB,oBAAoB;QACpB,mBAAmB;KACpB,CAAC;IACF,GAAG,OAAO,CAAC,aAAa,EAAE;QACxB,aAAa;QACb,WAAW;QACX,WAAW;QACX,UAAU;QACV,WAAW;QACX,WAAW;QACX,WAAW;QACX,UAAU;QACV,UAAU;QACV,YAAY;QACZ,cAAc;QACd,cAAc;QACd,YAAY;QACZ,UAAU;QACV,UAAU;QACV,eAAe;QACf,SAAS;QACT,WAAW;QACX,QAAQ;QACR,UAAU;QACV,QAAQ;QACR,YAAY;QACZ,cAAc;KACf,CAAC;CACH,CAAC,CAAC;AAEH;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,IAAY;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACnD,OAAO,oBAAY,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AAClG,CAAC;AAUD,0GAA0G;AAC1G,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CACpC,WAAuG,EACvG,KAA0B;IAE1B,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1C,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,WAAW,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACnC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC;YAAE,OAAO;QAEzC,MAAM,IAAI,GAAG,eAAe,KAAK,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,CAAC,QAAQ,GAAG,EAAE,EAAE,MAAM,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACjE,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,oBAAY,CAAC,iBAAiB,EAAE,CAAC;YACjE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,GAAG,IAAI,UAAU,EAAE,OAAO,EAAE,oBAAoB,oBAAY,CAAC,iBAAiB,8CAA8C,KAAK,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACnM,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5H,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,4BAA4B,EAAE,IAAI,EAAE,GAAG,IAAI,UAAU,EAAE,OAAO,EAAE,yEAAyE,EAAE,CAAC,CAAC;QACnK,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,IAAI,UAAU,EAAE,OAAO,EAAE,8EAA8E,EAAE,CAAC,CAAC;QAC9J,CAAC;QAED,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,UAAU,CAAC;YAAE,OAAO;QAErD,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACxD,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,GAAG,IAAI,gBAAgB,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC,UAAU,uFAAuF,EAAE,CAAC,CAAC;QACtM,CAAC;aAAM,IAAI,aAAa,CAAC,MAAM,GAAG,oBAAY,CAAC,uBAAuB,EAAE,CAAC;YACvE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,yBAAyB,EAAE,IAAI,EAAE,GAAG,IAAI,gBAAgB,EAAE,OAAO,EAAE,oBAAoB,oBAAY,CAAC,uBAAuB,aAAa,EAAE,CAAC,CAAC;QAClK,CAAC;aAAM,IAAI,cAAc,CAAC,aAAa,CAAC,KAAK,OAAO,EAAE,CAAC;YACrD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,+BAA+B,EAAE,IAAI,EAAE,GAAG,IAAI,gBAAgB,EAAE,OAAO,EAAE,+DAA+D,EAAE,CAAC,CAAC;QAClK,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/commonjs/apps/route.d.ts

@@ -0,0 +1,28 @@
+import { type SurfaceId } from "./surfaces.js";
+/** Values the destination view receives as `environment.navParams`, never as `queryParams`. Strings only. */
+export type EnvParams = Record<string, string>;
+export type RouteDescriptor = 
+/** The screen a surface lives on, optionally for one record (detail surfaces). */
+{
+    type: "surface";
+    surfaceId: SurfaceId;
+    objectId?: number;
+    envParams?: EnvParams;
+}
+/** The calling app's own settings page (the `settings` surface). */
+ | {
+    type: "appSettings";
+    envParams?: EnvParams;
+}
+/**
+ * One of the calling app's own pages, by concrete path in the app's space (`/reports/7`, not
+ * `/reports/:id`). The host checks that it matches one of the app's routes offered in the
+ * current portal. There is no `appId`: an app can only open its own pages.
+ */
+ | {
+    type: "appPage";
+    path: string;
+    envParams?: EnvParams;
+};
+export declare function isRouteDescriptor(value: unknown): value is RouteDescriptor;
+//# sourceMappingURL=route.d.ts.map

package/dist/commonjs/apps/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../src/apps/route.ts"],"names":[],"mappings":"AAUA,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE3D,6GAA6G;AAC7G,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/C,MAAM,MAAM,eAAe;AACzB,kFAAkF;AAChF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE;AACrF,oEAAoE;GAClE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE;AAChD;;;;GAIG;GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAE7D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAuB1E"}

package/dist/commonjs/apps/route.js

@@ -0,0 +1,42 @@
+"use strict";
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md.
+ *
+ * Apps never navigate by host path. They name a destination and the host maps it to its own
+ * routes, which keeps host URLs free to change and stops an app from steering users to arbitrary
+ * pages. The one path an app writes, `appPage`, is a path inside its own pages space.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRouteDescriptor = isRouteDescriptor;
+const routes_js_1 = require("./routes.js");
+const surfaces_js_1 = require("./surfaces.js");
+function isRouteDescriptor(value) {
+    if (typeof value !== "object" || value === null || !("type" in value))
+        return false;
+    const v = value;
+    if (v["envParams"] !== undefined && !isEnvParams(v["envParams"]))
+        return false;
+    switch (v["type"]) {
+        case "surface":
+            // Only catalog surfaces of a portal: the host has no route for anything else. Safe integers
+            // only, so a record id is never silently rounded on its way through JSON. The portal-less
+            // surfaces belong to an app and are reachable only through descriptors that always mean the
+            // calling app (`appSettings`, `appPage`): as a plain surface, `objectId` would name another
+            // app's settings page or pages.
+            return typeof v["surfaceId"] === "string" && ((0, surfaces_js_1.getSurface)(v["surfaceId"])?.portal ?? null) !== null &&
+                (v["objectId"] === undefined || (Number.isSafeInteger(v["objectId"]) && v["objectId"] > 0));
+        case "appSettings":
+            return true;
+        case "appPage":
+            // Concrete paths only, in the route grammar: no params, dots, escapes or empty segments.
+            return (0, routes_js_1.isConcreteRoutePath)(v["path"]);
+        default:
+            return false;
+    }
+}
+function isEnvParams(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) &&
+        Object.values(value).every((v) => typeof v === "string");
+}
+//# sourceMappingURL=route.js.map

package/dist/commonjs/apps/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../src/apps/route.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAoBH,8CAuBC;AAzCD,2CAAkD;AAClD,+CAA2D;AAiB3D,SAAgB,iBAAiB,CAAC,KAAc;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAEpF,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,CAAC,CAAC,WAAW,CAAC,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAE/E,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QAClB,KAAK,SAAS;YACZ,4FAA4F;YAC5F,0FAA0F;YAC1F,4FAA4F;YAC5F,4FAA4F;YAC5F,gCAAgC;YAChC,OAAO,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,QAAQ,IAAI,CAAC,IAAA,wBAAU,EAAC,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,IAAI,IAAI,CAAC,KAAK,IAAI;gBAChG,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAK,CAAC,CAAC,UAAU,CAAY,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5G,KAAK,aAAa;YAChB,OAAO,IAAI,CAAC;QACd,KAAK,SAAS;YACZ,yFAAyF;YACzF,OAAO,IAAA,+BAAmB,EAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QACxC;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;AAC7D,CAAC"}

package/dist/commonjs/apps/routes.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A declared route path: `/`, or `/seg(/seg)*` where each segment is static or a `:param`. No dots,
+ * percent-escapes, upper case, empty segments or trailing slash, so no path can climb out of the
+ * app's own space. `pages` is not reserved inside that space: `/pages/foo` is an ordinary path.
+ */
+export declare const ROUTE_PATH_PATTERN = "^/(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|:[a-z][a-z0-9_]*)(?:/(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|:[a-z][a-z0-9_]*))*)?$";
+/** A concrete path an app navigates to (`{ type: "appPage" }`): the same grammar without params. */
+export declare const CONCRETE_ROUTE_PATH_PATTERN = "^/(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*)?$";
+export declare const ROUTE_PATH_MAX_CHARS = 200;
+/** Segments in one path; `/` has none. */
+export declare const ROUTE_PATH_MAX_SEGMENTS = 8;
+/** Routes in one manifest. */
+export declare const APP_ROUTES_MAX = 50;
+/** A declared route path: the {@link ROUTE_PATH_PATTERN} grammar, ≤ 200 characters and ≤ 8 segments. */
+export declare function isRoutePath(value: unknown): value is string;
+/** A concrete route path (no `:param` segments) within the same limits as a declared one. */
+export declare function isConcreteRoutePath(value: unknown): value is string;
+/**
+ * Renames every param segment to `:_`. Two paths that normalize to the same string claim the same
+ * URLs (`/vendors/:id` and `/vendors/:vendor_id`), so a manifest may declare only one of them.
+ */
+export declare function normalizeRoutePath(path: string): string;
+export interface RouteSetIssue {
+    /** Index of the offending entry in `routes`. */
+    index: number;
+    field: "path" | "portals" | "navigation";
+    message: string;
+}
+/**
+ * The rules over a set of routes that a pattern alone cannot express: the segment cap, a param
+ * name used twice in one path, two paths claiming the same URLs, and a repeated portal. Grammar,
+ * length and the per-field limits are the schema's job; a path that fails the grammar is skipped
+ * here. The zod schema and `apps-cli validate` both report these, and the server repeats them.
+ */
+export declare function routeSetIssues(routes: ReadonlyArray<{
+    path: string;
+    portals?: readonly string[] | undefined;
+    navigation?: unknown;
+}>): RouteSetIssue[];
+export interface AppRouteMatch<R> {
+    route: R;
+    /** Param values by name, percent-decoded. Always strings: the app parses ids itself. */
+    params: Record<string, string>;
+    /** Index of `route` in the list passed to {@link matchAppRoute}. */
+    index: number;
+}
+/**
+ * Finds the route a pathname in the app's own space renders (`/reports/7` for
+ * `/{portal}/apps/{appId}/pages/reports/7`), or `null` when none does.
+ *
+ * `pathname` is URL-encoded, as it appears in a URL: `/` or `/seg(/seg)*` with no empty segment,
+ * trailing slash, query or fragment (anything else matches nothing). A host that receives decoded
+ * segments encodes each with `encodeURIComponent` before joining them.
+ *
+ * A static route segment matches only the identical pathname segment. A param segment matches any
+ * other segment that decodes to a plain value (see `paramValue`); a segment containing `:` never
+ * matches a param. When several routes match, the one with a static segment at the first position
+ * where they differ wins (static before param, left to right); among equals, the first declared.
+ * Routes whose path is not in the grammar are ignored, so a stale or hand-edited feed entry can
+ * never match.
+ */
+export declare function matchAppRoute<R extends {
+    path: string;
+}>(routes: readonly R[], pathname: string): AppRouteMatch<R> | null;
+//# sourceMappingURL=routes.d.ts.map

package/dist/commonjs/apps/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/apps/routes.ts"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,2HAC2F,CAAC;AAE3H,oGAAoG;AACpG,eAAO,MAAM,2BAA2B,iFAAqD,CAAC;AAE9F,eAAO,MAAM,oBAAoB,MAAM,CAAC;AACxC,0CAA0C;AAC1C,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,8BAA8B;AAC9B,eAAO,MAAM,cAAc,KAAK,CAAC;AAkBjC,wGAAwG;AACxG,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE3D;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEnE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,GACrG,aAAa,EAAE,CAgDjB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAC;IACT,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACf;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACtD,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,QAAQ,EAAE,MAAM,GACf,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAazB"}