@spacefast/common 0.0.10 → 0.0.12

package/dist/docs/agent-setup.js

@@ -47,10 +47,12 @@ function isSafeHttpUrl(url) {
 }
 /**
  * The single shared grammar for handoff links:
- * `https://<app-origin>/agent/<documentId>#<secret>`. The document ID must match
+ * `<app-origin>/agent/<documentId>#<secret>`. The document ID must match
  * `[A-Za-z0-9_-]{1,512}` and the secret `[A-Za-z0-9_-]{16,512}` (the minimum keeps secrets
  * high-entropy and makes the public-projection leak check meaningful); the two must differ;
- * queries and embedded credentials are forbidden; HTTPS is required except on loopback hosts.
+ * queries and embedded credentials are forbidden. The URL must sit exactly on the caller's
+ * configured HTTP(S) app origin; that origin pin enforces scheme, hostname, and port without a
+ * second host allowlist that would reject legitimate dev or container origins.
  * Normalization is part of the contract: the input is WHATWG-URL-normalized first (backslashes,
  * dot segments, stray tab/CR/LF, empty userinfo, case, default ports), the grammar is enforced on
  * the normalized URL, and only the reconstructed canonical URL ever leaves this function.
@@ -58,13 +60,17 @@ function isSafeHttpUrl(url) {
  * grammar can never fork.
  */
 export function parseAgentHandoffUrl(value, expectedOrigin) {
-    let canonicalExpectedOrigin;
+    let expectedUrl;
     try {
-        canonicalExpectedOrigin = new URL(expectedOrigin).origin;
+        expectedUrl = new URL(expectedOrigin);
     }
     catch {
         throw new TypeError("Agent handoff expectedOrigin must be a valid URL origin.");
     }
+    if (expectedUrl.protocol !== "https:" && expectedUrl.protocol !== "http:") {
+        throw new TypeError("Agent handoff expectedOrigin must be an HTTP(S) origin.");
+    }
+    const canonicalExpectedOrigin = expectedUrl.origin;
     let url;
     try {
         url = new URL(value);
@@ -74,14 +80,15 @@ export function parseAgentHandoffUrl(value, expectedOrigin) {
     }
     const documentId = /^\/agent\/([^/]+)$/.exec(url.pathname)?.[1];
     const secret = url.hash.slice(1);
-    if (!isSafeHttpUrl(url) ||
-        url.origin !== canonicalExpectedOrigin ||
+    if (url.origin !== canonicalExpectedOrigin ||
+        url.username !== "" ||
+        url.password !== "" ||
         value.includes("?") ||
         !documentId ||
         !opaqueHandoffDocumentId.test(documentId) ||
         !opaqueHandoffSecret.test(secret) ||
         documentId === secret) {
-        throw new TypeError("Agent handoff URL must be an HTTPS /agent/<id> URL with one opaque fragment secret (16-512 chars, distinct from the id) and no credentials or query (HTTP is allowed on loopback hosts).");
+        throw new TypeError("Agent handoff URL must be an /agent/<id> URL on the app origin with one opaque fragment secret (16-512 chars, distinct from the id) and no credentials or query.");
     }
     return { documentId, documentUrl: `${url.origin}${url.pathname}`, secret };
 }
@@ -282,6 +289,7 @@ export function aiInstructionsText() {
         "```",
         "",
         "Request `mcp:tools` plus the API scopes the tools need: `teams:read` for team context,",
+        "`teams:create` for creating teams,",
         "`spaces:read` for status, versions, diffs, and logs, `spaces:write` for claim/create/update,",
         "`publish:write` for publish and rollback, and `domains:read`/`domains:write` for domain",
         "inventory, DNS diagnostics, assignment, verification, and mutation. Hosted MCP does not read",

package/dist/docs/agent-solutions.js

@@ -22,7 +22,7 @@ function hostedMcpText(label, guideUrl) {
         "Transport: Streamable HTTP",
         "Resource: https://mcp.spacefast.com",
         "Minimum scope: mcp:tools",
-        "Common scopes: teams:read spaces:read spaces:write publish:write domains:read domains:write",
+        "Common scopes: teams:read teams:create spaces:read spaces:write publish:write domains:read domains:write",
         "",
         "Hosted MCP is for cloud/browser agents. It does not read local paths; use the hosted workspace tools or signed uploads for artifacts.",
         `Guide: ${guideUrl}`,

package/dist/docs/catalog.d.ts

@@ -24,8 +24,6 @@ export interface DocEntry {
 }
 /** Base URL all bundled docs links resolve against. */
 export declare const DOCS_BASE_URL = "https://spacefast.com/docs";
-/** Base URL for the standalone recipe pages (served at /recipes, not /docs). */
-export declare const RECIPES_BASE_URL = "https://spacefast.com/recipes";
 export declare const DOCS_CATALOG: readonly [{
     readonly slug: "quickstart";
     readonly title: "Quickstart";
@@ -244,13 +242,13 @@ export declare const DOCS_CATALOG: readonly [{
     readonly body: "Connect a repository with `sf git connect`; each push runs your build on Spacefast and publishes a version, with branches and pull requests getting preview URLs.";
 }, {
     readonly slug: "collab";
-    readonly title: "Collaboration and annotations";
+    readonly title: "Comments";
     readonly kind: "guide";
     readonly tier: "full";
-    readonly summary: "Leave review comments on a published space.";
-    readonly keywords: readonly ["collab", "annotations", "comments", "review", "feedback", "annotate"];
+    readonly summary: "Leave comments directly on a space.";
+    readonly keywords: readonly ["comments", "collaboration", "feedback"];
     readonly url: "https://spacefast.com/docs/collab";
-    readonly body: "Annotate a live space with review comments and resolve them from the CLI with `sf annotations` or in the dashboard.";
+    readonly body: "Leave comments directly on a live space and archive them from the dashboard or with `sf comments`.";
 }, {
     readonly slug: "analytics";
     readonly title: "Analytics";
@@ -618,7 +616,7 @@ export declare const DOCS_CATALOG: readonly [{
     readonly tier: "full";
     readonly summary: "Point your own domain at a space with automatic TLS.";
     readonly keywords: readonly ["domain", "custom domain", "dns", "tls", "https", "recipe"];
-    readonly url: "https://spacefast.com/recipes/custom-domain";
+    readonly url: "https://spacefast.com/help/domains";
     readonly body: "Add the domain with `sf domains add`, set the DNS records Spacefast prints, and wait for `sf domains check` to report a ready certificate.";
 }, {
     readonly slug: "recipes/password-protect";
@@ -627,7 +625,7 @@ export declare const DOCS_CATALOG: readonly [{
     readonly tier: "full";
     readonly summary: "Put one shared password in front of a whole space.";
     readonly keywords: readonly ["password", "protect", "private", "access", "gate", "recipe"];
-    readonly url: "https://spacefast.com/recipes/password-protect-a-space";
+    readonly url: "https://spacefast.com/help/access";
     readonly body: "Run `sf password set` to gate a space behind a single shared secret; clear it later with `sf password clear`.";
 }, {
     readonly slug: "recipes/redirects";
@@ -636,7 +634,7 @@ export declare const DOCS_CATALOG: readonly [{
     readonly tier: "reference";
     readonly summary: "Add redirect rules that ship and roll back with a version.";
     readonly keywords: readonly ["redirect", "rewrite", "routing", "301", "recipe"];
-    readonly url: "https://spacefast.com/recipes/redirects";
+    readonly url: "https://spacefast.com/help/redirects";
     readonly body: "Add redirect rules to a `_redirects` file at your publish root so they publish as part of the version and roll back with it.";
 }, {
     readonly slug: "recipes/migrate-dns";
@@ -645,6 +643,6 @@ export declare const DOCS_CATALOG: readonly [{
     readonly tier: "reference";
     readonly summary: "Cut traffic over to a Spacefast-served domain safely.";
     readonly keywords: readonly ["dns", "migrate", "cutover", "domain", "nameserver", "recipe"];
-    readonly url: "https://spacefast.com/recipes/custom-domain";
+    readonly url: "https://spacefast.com/help/domains";
     readonly body: "Pre-stage the domain with `sf domains add`, verify the certificate is ready with `sf domains check`, then update DNS to flip traffic with zero downtime.";
 }, ...DocEntry[]];

package/dist/docs/catalog.js

@@ -21,8 +21,6 @@ import { ERROR_DOCS } from "./error-docs.js";
 export const DOC_KINDS = ["guide", "cli", "api", "recipe", "workflow", "error"];
 /** Base URL all bundled docs links resolve against. */
 export const DOCS_BASE_URL = "https://spacefast.com/docs";
-/** Base URL for the standalone recipe pages (served at /recipes, not /docs). */
-export const RECIPES_BASE_URL = "https://spacefast.com/recipes";
 const HAND_WRITTEN_DOCS_CATALOG = [
     // ----- Guides -----------------------------------------------------------
     {
@@ -283,13 +281,13 @@ const HAND_WRITTEN_DOCS_CATALOG = [
     },
     {
         slug: "collab",
-        title: "Collaboration and annotations",
+        title: "Comments",
         kind: "guide",
         tier: "full",
-        summary: "Leave review comments on a published space.",
-        keywords: ["collab", "annotations", "comments", "review", "feedback", "annotate"],
+        summary: "Leave comments directly on a space.",
+        keywords: ["comments", "collaboration", "feedback"],
         url: `${DOCS_BASE_URL}/collab`,
-        body: "Annotate a live space with review comments and resolve them from the CLI with `sf annotations` or in the dashboard.",
+        body: "Leave comments directly on a live space and archive them from the dashboard or with `sf comments`.",
     },
     {
         slug: "analytics",
@@ -701,7 +699,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         tier: "full",
         summary: "Point your own domain at a space with automatic TLS.",
         keywords: ["domain", "custom domain", "dns", "tls", "https", "recipe"],
-        url: `${RECIPES_BASE_URL}/custom-domain`,
+        url: "https://spacefast.com/help/domains",
         body: "Add the domain with `sf domains add`, set the DNS records Spacefast prints, and wait for `sf domains check` to report a ready certificate.",
     },
     {
@@ -711,7 +709,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         tier: "full",
         summary: "Put one shared password in front of a whole space.",
         keywords: ["password", "protect", "private", "access", "gate", "recipe"],
-        url: `${RECIPES_BASE_URL}/password-protect-a-space`,
+        url: "https://spacefast.com/help/access",
         body: "Run `sf password set` to gate a space behind a single shared secret; clear it later with `sf password clear`.",
     },
     {
@@ -721,7 +719,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         tier: "reference",
         summary: "Add redirect rules that ship and roll back with a version.",
         keywords: ["redirect", "rewrite", "routing", "301", "recipe"],
-        url: `${RECIPES_BASE_URL}/redirects`,
+        url: "https://spacefast.com/help/redirects",
         body: "Add redirect rules to a `_redirects` file at your publish root so they publish as part of the version and roll back with it.",
     },
     {
@@ -731,7 +729,7 @@ const HAND_WRITTEN_DOCS_CATALOG = [
         tier: "reference",
         summary: "Cut traffic over to a Spacefast-served domain safely.",
         keywords: ["dns", "migrate", "cutover", "domain", "nameserver", "recipe"],
-        url: `${RECIPES_BASE_URL}/custom-domain`,
+        url: "https://spacefast.com/help/domains",
         body: "Pre-stage the domain with `sf domains add`, verify the certificate is ready with `sf domains check`, then update DNS to flip traffic with zero downtime.",
     },
 ];

package/dist/docs/error-docs.js

@@ -36,6 +36,10 @@ export const ERROR_DOCS = {
         summary: "This user already has the maximum number of pending handoffs for the Space.",
         fix: "Redeem or revoke an existing pending handoff for the Space before creating another.",
     },
+    agent_handoff_origin_unsupported: {
+        summary: "The dashboard origin this deployment is configured with cannot mint canonical agent handoff links.",
+        fix: "Point SPACEFAST_DASHBOARD_URL at a valid HTTP(S) origin; if you cannot change it, contact support.",
+    },
     ambiguous_space_slug: {
         summary: "The slug matches spaces in more than one of your teams, so it cannot be resolved.",
         fix: "Pass a teamRef alongside the slug, or reference the space by its spc_ id.",
@@ -220,13 +224,13 @@ export const ERROR_DOCS = {
         summary: "CSAM enforcement policy cannot be set below the mandatory account-suspend floor.",
         fix: "Set the CSAM category enforcement tier to account suspension.",
     },
-    datacenters_unavailable: {
-        summary: "Placement regions are temporarily unavailable.",
-        fix: "Retry after the datacenter list has synced.",
+    custom_certificates_require_dedicated_site: {
+        summary: "Custom certificates are unavailable while this space uses shared placement.",
+        fix: "Move the space to dedicated placement before managing custom certificates.",
     },
     data_location_immutable: {
         summary: "This request tried to change data location through an immutable path.",
-        fix: "Use PATCH /v1/spaces/{id} to queue a region move when region changes are supported for this space.",
+        fix: "Data location is fixed when the space is created and cannot be changed afterwards. Create a new space in the region you want.",
     },
     device_authorization_failed: {
         summary: "The device login request failed and cannot be completed.",
@@ -476,6 +480,10 @@ export const ERROR_DOCS = {
         summary: "Basic-Auth via _headers is not available on the Free plan.",
         fix: "Use space password protection instead. Still stuck? POST /v1/feedback with the error code and request id.",
     },
+    google_play_webhook_identity_not_configured: {
+        summary: "Google Play Pub/Sub push authentication is not configured on this deployment.",
+        fix: "Configure the exact push audience and dedicated Pub/Sub service-account email before enabling RTDN delivery.",
+    },
     idempotency_conflict_in_progress: {
         summary: "Another request with the same Idempotency-Key is still in flight.",
         fix: "Wait for the original request to finish; its response will be replayed.",
@@ -544,6 +552,10 @@ export const ERROR_DOCS = {
         summary: "A file path in the request is not a valid space path.",
         fix: "Use forward-slash relative paths without traversal segments.",
     },
+    invalid_google_play_webhook_identity: {
+        summary: "The Google Play notification did not carry a valid Pub/Sub push identity.",
+        fix: "Send the notification through the configured authenticated Pub/Sub push subscription.",
+    },
     invalid_grant: {
         summary: "The authorization grant is invalid or was already used.",
         fix: "Restart the login flow to obtain a new grant.",
@@ -660,6 +672,10 @@ export const ERROR_DOCS = {
         summary: `${BRAND.productName} no longer observes DNS control for this domain.`,
         fix: "Restore the documented DNS records, then re-run domain verification.",
     },
+    maintenance_in_progress: {
+        summary: "This change is temporarily unavailable while maintenance finishes.",
+        fix: "Wait for the Retry-After window, then send the same request again.",
+    },
     malware_detected: {
         summary: "Malware was detected in the uploaded content.",
         fix: "Remove the flagged files; contact support if you believe this is a false positive.",
@@ -917,8 +933,8 @@ export const ERROR_DOCS = {
         fix: "Retry shortly; if the site stays unreachable, contact support.",
     },
     runtime_not_provisioned: {
-        summary: "The space has no provisioned runtime yet.",
-        fix: "Wait for provisioning to finish; the operation receipt reports progress.",
+        summary: "The space has not served a published version yet, so it has no runtime data to read.",
+        fix: "Publish a version first. If a publish is already running, wait for it — the operation receipt reports progress.",
     },
     runtime_operation_missing: {
         summary: "The runtime operation referenced by this request was not found.",
@@ -960,6 +976,10 @@ export const ERROR_DOCS = {
         summary: "A secret variable was referenced in a template, which is blocked.",
         fix: "Templates may only substitute non-secret variables; remove the secret reference.",
     },
+    service_signature_invalid: {
+        summary: "The service request signature could not be verified.",
+        fix: "Sign the exact request method, path, body digest, timestamp, and a fresh nonce.",
+    },
     site_already_deleted: {
         summary: "The site was already deleted.",
         fix: "No action needed; the site is gone.",
@@ -1000,6 +1020,18 @@ export const ERROR_DOCS = {
         summary: "The slug is already in use within the relevant ownership scope.",
         fix: "Choose another slug or use the available suggestion returned by the API.",
     },
+    source_archive_decompression_timeout: {
+        summary: "The uploaded source archive did not finish decompressing within the validation limit.",
+        fix: "Reduce the archive's compressed complexity or split it into a smaller source upload, then retry.",
+    },
+    source_archive_expansion_ratio_exceeded: {
+        summary: "The uploaded source archive expands too much relative to its compressed size.",
+        fix: "Rebuild the archive without highly compressible filler or generated content, then upload it again.",
+    },
+    source_archive_validation_busy: {
+        summary: "The service is already validating its maximum number of source archives.",
+        fix: "Wait briefly and retry the upload.",
+    },
     space_already_claimed: {
         summary: "The space was already claimed; a claim can only succeed once.",
         fix: "If you are the agent that published this space, exchange your claim token once at POST /v1/anonymous-claim/exchange for a durable access token and keep publishing to the same spaceId. Otherwise ask the owner for access — do not publish a duplicate space.",
@@ -1088,6 +1120,34 @@ export const ERROR_DOCS = {
         summary: "This control file is not supported by the static runtime.",
         fix: "Remove the file; see the routing docs for supported convention files.",
     },
+    static_mount_path_conflict: {
+        summary: "The requested mount path overlaps another static mount on this space.",
+        fix: "Choose a path that is not equal to, above, or below an existing mount path.",
+    },
+    static_mount_source_not_ready: {
+        summary: "The website version that owns this mount is not ready.",
+        fix: "Wait for the website version to finish finalizing, then retry.",
+    },
+    static_mount_target_forbidden: {
+        summary: "The target space is not an authorized space in the same team.",
+        fix: "Choose another space in the source space's team and authenticate with read access to its versions.",
+    },
+    static_mount_target_in_use: {
+        summary: "A static mount dependency blocks changing or deleting this space.",
+        fix: "Remove the reported static mount before retrying the operation.",
+    },
+    static_mount_target_not_live: {
+        summary: "The target space does not have a production version to mount.",
+        fix: "Publish or promote a ready version on the target space, then retry.",
+    },
+    static_mount_target_not_ready: {
+        summary: "The target production version is not ready for static delivery.",
+        fix: "Wait for the target version to finish finalizing, then retry.",
+    },
+    static_mount_target_not_static: {
+        summary: "The target production version contains runtime functions.",
+        fix: "Promote a fully static target version or serve the dynamic application without a static mount.",
+    },
     static_runtime_control_path_not_supported: {
         summary: "This control path is not supported by the static runtime.",
         fix: "Remove the path from the upload.",
@@ -1368,10 +1428,6 @@ export const ERROR_DOCS = {
         summary: "The Zero endpoint artifact could not be parsed.",
         fix: "Rebuild the Zero project; do not edit generated artifact JSON by hand.",
     },
-    zero_artifact_missing: {
-        summary: "A Zero route points to an endpoint artifact that is missing.",
-        fix: "Declare the endpoint in zero_endpoints, then rebuild and publish again.",
-    },
     zero_artifact_path_invalid: {
         summary: "The Zero endpoint artifact path is invalid.",
         fix: "Rebuild the Zero routes so all artifact paths stay inside the version bundle.",
@@ -1380,10 +1436,6 @@ export const ERROR_DOCS = {
         summary: "The Zero endpoint artifact could not be read by the runtime.",
         fix: "Verify the version finalized with all generated Zero files present.",
     },
-    zero_artifact_untrusted: {
-        summary: "A Zero route points to an uploaded artifact that the runtime did not compile.",
-        fix: "Declare the endpoint in zero_endpoints so finalize generates trusted bytecode.",
-    },
     zero_auth_unavailable: {
         summary: "Hosted Zero auth is not configured for this deployment.",
         fix: "Finalize the Zero version with hosted auth URLs or use guest/local auth.",
@@ -1472,6 +1524,10 @@ export const ERROR_DOCS = {
         summary: "The Zero database operation has too many parameters.",
         fix: "Reduce the number of bound parameters or split the operation.",
     },
+    zero_db_transaction_active: {
+        summary: "The Zero runner tried to start a database transaction while one was already active.",
+        fix: "Rebuild with the current Zero runner and report the failure if it repeats.",
+    },
     zero_db_transaction_commit_failed: {
         summary: "The Zero database transaction could not be committed.",
         fix: "Retry after checking database connectivity and transaction conflicts.",
@@ -1480,6 +1536,14 @@ export const ERROR_DOCS = {
         summary: "The Zero database transaction mode is invalid.",
         fix: "Use a supported generated transaction mode.",
     },
+    zero_db_transaction_missing: {
+        summary: "The Zero runner tried to finish a database transaction that was not active.",
+        fix: "Rebuild with the current Zero runner and report the failure if it repeats.",
+    },
+    zero_db_transaction_rollback_failed: {
+        summary: "The Zero database transaction could not be rolled back cleanly.",
+        fix: "Inspect the affected database state before retrying, then report the failure.",
+    },
     zero_db_transaction_start_failed: {
         summary: "The Zero database transaction could not be started.",
         fix: "Check database connectivity and retry the mutation.",
@@ -1588,10 +1652,6 @@ export const ERROR_DOCS = {
         summary: "The Zero log query parameters are invalid.",
         fix: "Use valid cursor, limit, mutationName, and requestId parameters.",
     },
-    zero_lookup_invalid: {
-        summary: "The Zero lookup map contains an invalid path or action.",
-        fix: "Use normalized relative paths and valid finalized Zero actions.",
-    },
     zero_method_not_allowed: {
         summary: "The request method is not allowed for this Zero endpoint.",
         fix: "Call the endpoint with one of the methods declared by the Zero route.",
@@ -1648,6 +1708,14 @@ export const ERROR_DOCS = {
         summary: "The Zero request body exceeds the runtime size limit.",
         fix: "Send a smaller request body or move large payloads to blob/object storage.",
     },
+    zero_response_header_forbidden: {
+        summary: "A Zero endpoint attempted to set a platform-managed response header.",
+        fix: "Remove the reserved response header from the endpoint response.",
+    },
+    zero_response_header_invalid: {
+        summary: "A Zero endpoint response header is invalid or exceeds the header limits.",
+        fix: "Use ASCII header names, keep values under the size limits, and avoid duplicate names.",
+    },
     zero_response_too_large: {
         summary: "The Zero endpoint response exceeds the runtime size limit.",
         fix: "Return a smaller response body or paginate the data.",

package/dist/utils/access-grant.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeRule } from "../contracts/access.js";
+export declare const ACCESS_GRANT_GATE_RULE_ID = "access-grant-gate";
+export declare const ACCESS_GRANT_ADMISSION_RULE_ID = "access-grant-admission";
+export type AccessGrantExposure = {
+    anonymousAccess: "gated" | "gated_with_exceptions" | "partly_public" | "shadowed";
+    earlierAnonymousAllowRules: number;
+    earlierManagedAccessRules: number;
+    precedingTerminalRules: number;
+};
+export declare function withAccessGrantGate(rules: RuntimeRule[], grant: string): RuntimeRule[];
+export declare function withoutAccessGrantRule(rules: RuntimeRule[], selectedIndex: number): RuntimeRule[];
+export declare function isAccessGrantAdmissionRule(rule: RuntimeRule): boolean;
+export declare function isAccessGrantFallbackRule(rule: RuntimeRule): boolean;
+export declare function accessGrantExposure(rules: RuntimeRule[]): AccessGrantExposure;

package/dist/utils/access-grant.js

@@ -0,0 +1,88 @@
+// `sf access grant` and the dashboard's Grant access card share one canonical
+// pair: an authenticated admission allow plus an anonymous fallback challenge.
+// Repeated grants widen both rules' OR-list. The split is essential under
+// first-match evaluation: the admission can pass before managed challenges,
+// while the fallback closes otherwise-public traffic after those challenges.
+export const ACCESS_GRANT_GATE_RULE_ID = "access-grant-gate";
+export const ACCESS_GRANT_ADMISSION_RULE_ID = "access-grant-admission";
+export function withAccessGrantGate(rules, grant) {
+    // Raw access writes replace only the unmanaged lane. GET/PUT responses may
+    // include server-owned managed blocks, but sending those blocks back would
+    // be rejected and could let a client accidentally claim their ownership.
+    // Reserved access-grant rules are rebuilt as one canonical pair below.
+    const unmanagedRules = rules.filter((rule) => rule.managedBy === undefined &&
+        rule.id !== ACCESS_GRANT_ADMISSION_RULE_ID &&
+        rule.id !== ACCESS_GRANT_GATE_RULE_ID);
+    const existingRequiredGrants = rules.find((rule) => rule.id === ACCESS_GRANT_ADMISSION_RULE_ID)
+        ?.auth?.requiredGrants;
+    const fallbackRequiredGrants = rules.find((rule) => rule.id === ACCESS_GRANT_GATE_RULE_ID)?.auth
+        ?.requiredGrants;
+    const requiredGrants = [
+        ...new Set([...(existingRequiredGrants ?? fallbackRequiredGrants ?? []), grant]),
+    ];
+    return [
+        ...unmanagedRules,
+        {
+            id: ACCESS_GRANT_ADMISSION_RULE_ID,
+            match: {},
+            effect: "allow",
+            auth: { requiredGrants },
+            reasonCode: "identity_grant_admitted",
+        },
+        {
+            id: ACCESS_GRANT_GATE_RULE_ID,
+            match: {},
+            effect: "challenge",
+            auth: { requiredGrants },
+            reasonCode: "identity_grant_required",
+            message: "Sign in with an approved identity to continue.",
+        },
+    ];
+}
+export function withoutAccessGrantRule(rules, selectedIndex) {
+    const selectedRule = rules[selectedIndex];
+    const removesAccessGrant = selectedRule?.id === ACCESS_GRANT_ADMISSION_RULE_ID ||
+        selectedRule?.id === ACCESS_GRANT_GATE_RULE_ID;
+    return rules.filter((rule, index) => rule.managedBy === undefined &&
+        (removesAccessGrant
+            ? rule.id !== ACCESS_GRANT_ADMISSION_RULE_ID && rule.id !== ACCESS_GRANT_GATE_RULE_ID
+            : index !== selectedIndex));
+}
+export function isAccessGrantAdmissionRule(rule) {
+    return (rule.id === ACCESS_GRANT_ADMISSION_RULE_ID &&
+        rule.effect === "allow" &&
+        Object.keys(rule.match).length === 0 &&
+        rule.auth !== undefined);
+}
+export function isAccessGrantFallbackRule(rule) {
+    return (rule.id === ACCESS_GRANT_GATE_RULE_ID &&
+        rule.effect === "challenge" &&
+        Object.keys(rule.match).length === 0 &&
+        rule.auth !== undefined);
+}
+// The admission allow protects approved identities without preempting the
+// existing password/share/service challenge. The final fallback gate protects
+// public fallthrough. A terminal rule from an earlier effective lane can still
+// stop evaluation before admission; report that explicitly instead of claiming
+// the space is simply gated.
+export function accessGrantExposure(rules) {
+    const gateIndex = rules.findIndex(isAccessGrantFallbackRule);
+    const admissionIndex = rules.findIndex(isAccessGrantAdmissionRule);
+    const earlierRules = gateIndex === -1 ? rules : rules.slice(0, gateIndex);
+    const rulesBeforeAdmission = admissionIndex === -1 ? earlierRules : rules.slice(0, admissionIndex);
+    const precedingTerminalRules = rulesBeforeAdmission.filter((rule) => rule.effect === "challenge" || (rule.effect === "deny" && rule.auth === undefined)).length;
+    const earlierAnonymousAllowRules = earlierRules.filter((rule) => rule.effect === "allow" && !rule.auth).length;
+    const earlierManagedAccessRules = earlierRules.filter((rule) => rule.managedBy !== undefined && rule.effect === "allow").length;
+    return {
+        anonymousAccess: precedingTerminalRules > 0
+            ? "shadowed"
+            : earlierAnonymousAllowRules > 0
+                ? "partly_public"
+                : earlierManagedAccessRules > 0
+                    ? "gated_with_exceptions"
+                    : "gated",
+        earlierAnonymousAllowRules,
+        earlierManagedAccessRules,
+        precedingTerminalRules,
+    };
+}

package/dist/utils/access-match.d.ts

@@ -1,6 +1,12 @@
 export declare function filterGrantsByNamespace(grants: string[], namespaces: string[]): string[];
 export declare function grantGlobMatches(pattern: string, grant: string): boolean;
 export declare function grantsIntersect(grants: string[], requiredGrants: string[]): boolean;
+export declare function requiredGrantsForRule(rule: {
+    managedBy?: string | undefined;
+    auth?: {
+        requiredGrants: string[];
+    } | undefined;
+}): string[];
 export declare function grantsSatisfyRule(input: {
     grants: string[];
     requiredGrants: string[];
@@ -31,6 +37,7 @@ export type RuleMatchInput = {
     ipCidrs?: string[] | undefined;
     agent?: string | undefined;
     country?: string | undefined;
+    countryNotIn?: string[] | undefined;
     header?: {
         name: string;
         value: string;