@plitzi/sdk-server 0.33.2 → 0.34.1

package/dist/adapters/cloudAdapters.js

@@ -0,0 +1,303 @@
+//#region src/adapters/cloudAdapters.ts
+/**
+* A space fetched from Plitzi, for a server that is not Plitzi's.
+*
+* This is the missing half of self-hosting: `createJsonAdapters` serves a space somebody exported by hand, which
+* goes stale the moment it is edited, and everything else meant standing up a database. Here the space stays in
+* the builder — published, versioned, edited by whoever normally edits it — and this deployment reads it over the
+* same GraphQL query the browser-rendered SDK uses, with the same space key. What is served is the deployment's
+* own: its own domain, its own auth, its own actions, its own logs.
+*
+* **Plitzi is never in the critical path of a page.** A version is fetched once and then served from cache; the
+* live document refreshes behind the request rather than in front of it, and a refresh that fails leaves the last
+* good copy serving. A self-hosted site does not go down because somebody else's API did.
+*/
+/**
+* Plitzi's own server role, which serves GraphQL at its root — no `/graphql` path, exactly as the browser SDK
+* addresses it. Production is the default because production is where a self-hosted deployment reads from; a
+* staging Plitzi is the exception and says so.
+*/
+var PLITZI_SERVER_URL = "https://server.plitzi.com";
+/**
+* The one query. Written out rather than imported from the shared package's `gql` document because this runs in a
+* server with no Apollo in it: the wire format is a string, and a string is what a `fetch` needs.
+*/
+var SPACE_QUERY = `query InitQuery($environment: String!, $revision: Int) {
+  Space(environment: $environment, revision: $revision) {
+    schema {
+      settings
+      flat { id definition { label type initialState styleSelectors bindings interactions parentId rootId items } attributes }
+      pages
+      pageFolders { id name slug parentId }
+      variables { name type value subValues { when value } }
+    }
+    segments {
+      id
+      identifier
+      definition
+      schema {
+        settings
+        variables { name type value subValues { value when } }
+        flat { id definition { label type initialState styleSelectors bindings interactions parentId rootId items } attributes }
+      }
+      style { cache }
+    }
+    plugins { type resource settings }
+    style { variables cache }
+  }
+}`;
+/**
+* Which revision of an environment is current.
+*
+* A separate, tiny query on purpose: in latest mode this is what runs on a timer, and asking it is orders of
+* magnitude cheaper — for this deployment and for Plitzi — than pulling a whole space down to discover it did not
+* change. The space itself is fetched only when this answer moves.
+*/
+var LATEST_REVISION_QUERY = `query SpaceLatestRevisionQuery($environment: String!) {
+  SpaceLatestRevision(environment: $environment) {
+    snapshot { revision }
+  }
+}`;
+/**
+* GraphQL answers `flat` as a LIST; every reader of a schema indexes it BY ID (`schema.flat[pageId]`, and the same
+* for `parentId`/`rootId`/`items`). The two are the `SchemaRaw` and `Schema` types, and the conversion is the wire
+* format's whole difference from the runtime one.
+*
+* Without it nothing throws — an array is a perfectly good object — it just answers `undefined` to every lookup, so
+* the page router matches no page and every URL is a 404 on a space that fetched and parsed correctly.
+*/
+var byElementId = (flat) => {
+	if (!Array.isArray(flat)) return flat ?? {};
+	return flat.reduce((acum, element) => {
+		if (element.id) acum[element.id] = element;
+		return acum;
+	}, {});
+};
+/** The runtime shape of a schema: the wire's `flat` list, keyed. */
+var toSchema = (schema) => ({
+	...schema,
+	flat: byElementId(schema.flat)
+});
+/**
+* Segments arrive as a list and are read by identifier, which is how every other reader of a space holds them. Each
+* one carries a schema of its own, so its `flat` needs the same keying the space's does.
+*/
+var byIdentifier = (segments) => (segments ?? []).reduce((acum, segment) => {
+	const entry = segment;
+	const identifier = entry.identifier;
+	if (!identifier || identifier in acum) return acum;
+	return {
+		...acum,
+		[identifier]: {
+			...entry,
+			...entry.schema && { schema: toSchema(entry.schema) }
+		}
+	};
+}, {});
+/**
+* The `scope` claim, read without verifying anything.
+*
+* Verification is the server's and this cannot do it — there is no signing key here, and a key this deployment does
+* not hold could not be checked anyway. Reading the claim is enough for what this is for: telling the operator, at
+* startup, that they pasted the wrong one of their two keys.
+*/
+var scopeOf = (token) => {
+	const payload = token.split(".")[1];
+	if (!payload) return;
+	try {
+		const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		return typeof claims.scope === "string" ? claims.scope : void 0;
+	} catch {
+		return;
+	}
+};
+/**
+* Refuse the PUBLIC key here, where the mistake is cheap, rather than as a 401 an hour later.
+*
+* The two keys are not interchangeable and the difference is the whole security model. A `render` key is embedded in
+* every published page, so anyone who views source has it; what keeps a copied one from working is that a browser is
+* made to state the origin it is presenting from, and that statement is checked. A server has no such statement to
+* make — which is exactly why a server must not be reading with the public key: if it could, a render key lifted
+* from someone else's site would be enough to serve a byte-identical clone of it from here.
+*
+* So self-hosting has a credential of its own. It is secret, issued once, bound to no domain, and revocable on its
+* own row without touching the published site's key.
+*/
+var assertHostKey = (webKey) => {
+	const scope = scopeOf(webKey);
+	if (scope === void 0 || scope === "space:host") return;
+	if (scope === "space:render") throw new Error("createCloudAdapters was given the space’s PUBLIC render key. That key is embedded in published pages and is only honoured from the origins it declares, so a server cannot present it. Issue a host key instead (Credentials → “Self-hosting” in the builder, or POST /spaces/{id}/tokens/host) and keep it secret — it is not safe to commit or to ship in a page.");
+	throw new Error(`createCloudAdapters needs a space host key; this one is scoped "${scope}".`);
+};
+var createCloudAdapters = (config) => {
+	const { serverUrl = PLITZI_SERVER_URL, webKey, environment = "main", revision, cacheSeconds = 60, cache, spaceId = 1, deployment, fetchImpl = fetch } = config;
+	assertHostKey(webKey);
+	/** `main` is the document somebody is editing right now. Nothing about it is worth remembering for a minute. */
+	const isLive = (env) => env === "main";
+	/** A version somebody named: fetched once, kept for good, because a published revision cannot change. */
+	const isPinned = (env, rev) => !isLive(env) && typeof rev === "number" && rev > 0;
+	const post = async (query, variables, what) => {
+		try {
+			const response = await fetchImpl(serverUrl, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					authorization: `Bearer ${webKey}`
+				},
+				body: JSON.stringify({
+					query,
+					variables
+				})
+			});
+			if (!response.ok) {
+				console.error(`[CloudAdapters] ${what} answered ${response.status}`);
+				return;
+			}
+			const payload = await response.json();
+			if (payload.errors?.length) {
+				console.error(`[CloudAdapters] ${what}: ${payload.errors.map((error) => error.message).join("; ")}`);
+				return;
+			}
+			return payload.data;
+		} catch (error) {
+			console.error(`[CloudAdapters] ${what} could not be reached:`, error.message);
+			return;
+		}
+	};
+	const fetchSpace = async (env, rev) => {
+		const space = (await post(SPACE_QUERY, {
+			environment: env,
+			revision: rev ?? null
+		}, `space ${env}@${rev ?? "latest"}`))?.Space;
+		if (!space?.schema) return;
+		return {
+			schema: toSchema(space.schema),
+			style: space.style,
+			plugins: space.plugins,
+			segments: byIdentifier(space.segments)
+		};
+	};
+	const fetchLatestRevision = async (env) => {
+		return (await post(LATEST_REVISION_QUERY, { environment: env }, `latest revision of ${env}`))?.SpaceLatestRevision?.snapshot?.revision;
+	};
+	const cacheKey = (env, rev) => `plitzi:space:${env}:${rev}`;
+	const held = /* @__PURE__ */ new Map();
+	/** One request per key at a time: a burst of renders on a cold cache joins the first, it does not multiply it. */
+	const inFlight = /* @__PURE__ */ new Map();
+	const once = (key, run) => {
+		const pending = inFlight.get(key);
+		if (pending) return pending;
+		const request = run().finally(() => inFlight.delete(key));
+		inFlight.set(key, request);
+		return request;
+	};
+	/** Reads a published revision through the shared cache, then the network, and writes back what it learned. */
+	const loadRevision = (env, rev) => {
+		const key = cacheKey(env, rev);
+		return once(key, async () => {
+			try {
+				const stored = await cache?.get(key);
+				if (stored) {
+					const data = JSON.parse(stored);
+					held.set(env, {
+						revision: rev,
+						data,
+						checkedAt: Date.now()
+					});
+					return data;
+				}
+			} catch {}
+			const fetched = await fetchSpace(env, rev);
+			if (!fetched) return;
+			held.set(env, {
+				revision: rev,
+				data: fetched,
+				checkedAt: Date.now()
+			});
+			await cache?.set(key, JSON.stringify(fetched)).catch(() => void 0);
+			return fetched;
+		});
+	};
+	/**
+	* Latest mode: find out which revision is current, and fetch the space only if that moved.
+	*
+	* The probe is the thing on the timer, not the space. A deployment that publishes once a week asks Plitzi for a
+	* revision number every minute and for a space once — and a publish is live within one window rather than
+	* whenever a blanket TTL happened to fall.
+	*
+	* A probe that fails leaves `checkedAt` alone so the next request tries again, and leaves the held copy serving.
+	*/
+	const refreshLatest = async (env) => {
+		const current = await fetchLatestRevision(env);
+		const previous = held.get(env);
+		if (current === void 0) return previous?.data;
+		if (previous && previous.revision === current) {
+			previous.checkedAt = Date.now();
+			return previous.data;
+		}
+		return await loadRevision(env, current) ?? previous?.data;
+	};
+	/**
+	* The space, and how hard this deployment leans on Plitzi to get it.
+	*
+	* - **`main`**: read live, every time. It is being edited; a cached answer is a wrong one.
+	* - **A pinned revision**: from cache forever after the first read. It cannot change.
+	* - **Latest**: the held copy is served immediately and a revision probe runs behind it once the window is up.
+	*   After the first render no page ever waits on Plitzi, and a failed probe or fetch changes nothing — the last
+	*   good copy keeps serving, because a self-hosted site going blank over somebody else's bad minute is not a
+	*   trade worth making.
+	*/
+	const getOfflineData = async (_spaceId, env, rev) => {
+		if (isLive(env)) return once(`live:${env}`, () => fetchSpace(env));
+		const pinned = rev ?? revision;
+		if (pinned !== void 0 && isPinned(env, pinned)) {
+			const already = held.get(env);
+			return already?.revision === pinned ? already.data : loadRevision(env, pinned);
+		}
+		const current = held.get(env);
+		if (!current) return refreshLatest(env);
+		if (Date.now() - current.checkedAt >= cacheSeconds * 1e3) {
+			current.checkedAt = Date.now();
+			refreshLatest(env).catch(() => void 0);
+		}
+		return current.data;
+	};
+	/**
+	* Every request is this one space.
+	*
+	* There is no host-to-space mapping to make: the key names the space, so a deployment that serves two of them
+	* builds two servers or supplies its own resolver — which is more honest than a lookup table that silently
+	* serves the wrong space when a domain is added and this is not.
+	*
+	* The revision it reports is the one actually being served, which in latest mode is whatever the last probe
+	* found: a deployment reading `at: { environment, revision }` must be told the version its page was built from,
+	* not the zero that means "whatever is live".
+	*/
+	const getSpaceDeployment = async () => {
+		if (isLive(environment)) return {
+			...deployment,
+			spaceId,
+			environment,
+			revision: 0
+		};
+		if (isPinned(environment, revision)) return {
+			...deployment,
+			spaceId,
+			environment,
+			revision
+		};
+		if (!held.has(environment)) await refreshLatest(environment);
+		return {
+			...deployment,
+			spaceId,
+			environment,
+			revision: held.get(environment)?.revision ?? 0
+		};
+	};
+	return {
+		getOfflineData,
+		getSpaceDeployment
+	};
+};
+//#endregion
+export { createCloudAdapters, createCloudAdapters as default };

package/dist/adapters/space/index.d.ts

@@ -0,0 +1,93 @@
+import { SpaceCache, SpaceResolution, SpaceResolver } from './types';
+import { SSRRequest, SSRSpaceDeployment } from '@plitzi/sdk-shared';
+export interface FrameAncestorsConfig {
+    /** The domains this space declared. Usually the origins on its public credential. */
+    find: (spaceId: number) => Promise<string[]>;
+    /** Always allowed on top of them — this deployment's own hosts, because a builder previews in an iframe. */
+    floor?: string[];
+    /** Cache the domain list too. Dropped by `invalidate.domains(spaceId)` when the owner edits it. */
+    cache?: boolean;
+}
+export interface SpaceAdaptersConfig {
+    /**
+     * How a request becomes a space, in order. The first resolver to answer wins, and one that REFUSES ends the
+     * chain — see {@link SpaceResolver}.
+     *
+     * Order is the only control here, and it is enough: put `authoringPreview` first so a credentialed request is
+     * never served as an anonymous visitor, and put a `fixedSpace` last if there should be no such thing as a host
+     * this server does not know.
+     */
+    resolvers: SpaceResolver[];
+    cache?: SpaceCache;
+    /** Default 300. */
+    ttlSeconds?: number;
+    /**
+     * What a resolution is cached under, or `undefined` for a request that must not be cached at all.
+     *
+     * The default is the hostname, **except** for a request presenting a credential, which is not cached in either
+     * direction. The cache is shared and keyed by host, while a credential can resolve the same host to a different
+     * space — so a hit would serve one visitor's preview to the next, and a write would poison the host for everyone.
+     */
+    cacheKey?: (req: SSRRequest) => string | undefined;
+    /**
+     * Who may put this space in an iframe. Applied to every resolution, which is the point of it living here: a
+     * deployment that derives it per branch eventually forgets a branch, and the branch it forgets serves a space
+     * framable by anyone.
+     */
+    frameAncestors?: FrameAncestorsConfig;
+    /**
+     * The last word, for whatever is this deployment's alone — which plugins a space loads, template props, a
+     * per-tenant theme. Runs on every resolution, after everything above.
+     */
+    decorate?: (resolution: SpaceResolution, req: SSRRequest) => Promise<Partial<SpaceResolution>>;
+    /** What an unresolved request gets. Default `404 Space not found`. */
+    notFound?: {
+        code: number;
+        message: string;
+    };
+    /** Reported, never thrown: a resolution that fails is one bad request, not a dead server. */
+    onError?: (error: unknown, req?: SSRRequest) => void;
+}
+/**
+ * `getSpaceDeployment`, assembled.
+ *
+ * Answering "which space is this request for" is the same shape everywhere and the same *rules* everywhere — try
+ * the ways a host can name a space, in order; never serve a credentialed request from a shared cache; derive the
+ * framing policy from what the space declared; say 404 rather than leaking whether a space exists. What differs
+ * between deployments is only where the rows are, which is what a resolver is.
+ *
+ * ```ts
+ * const spaces = createSpaceAdapters({
+ *   resolvers: [
+ *     authoringPreview({ hosts, resolveGrant: auth.identity.resolveGrant, find: findSpace }),
+ *     wildcardSubdomain({ suffix: 'example.app', find: findSpaceBySlug }),
+ *     verifiedDomain(findDeploymentByDomain)
+ *   ],
+ *   cache: redisCache,
+ *   frameAncestors: { find: findSpaceDomains, floor: hosts, cache: true }
+ * });
+ *
+ * createServer({ adapters: { ...spaces.adapters, getOfflineData } });
+ * ```
+ */
+export declare const createSpaceAdapters: (config: SpaceAdaptersConfig) => {
+    /** Spread into `createServer({ adapters })` beside whatever answers `getOfflineData`. */
+    adapters: {
+        getSpaceDeployment: (req: SSRRequest) => Promise<SSRSpaceDeployment>;
+    };
+    getSpaceDeployment: (req: SSRRequest) => Promise<SSRSpaceDeployment>;
+    /**
+     * Drop what a change made untrue. Both matter the moment an owner edits something through an API: without the
+     * first a domain keeps resolving to the space it used to, and without the second a space stays framable by a
+     * site whose permission was just withdrawn — in both cases until the TTL, which is not a security boundary.
+     */
+    invalidate: {
+        resolution: (key: string) => Promise<void>;
+        domains: (spaceId: number) => Promise<void>;
+    };
+};
+export type SpaceAdapters = ReturnType<typeof createSpaceAdapters>;
+export { authoringPreview, fixedSpace, presentsCredential, verifiedDomain, wildcardSubdomain } from './resolvers';
+export { createMemoryCache, refuse } from './types';
+export type { AuthoringPreviewOptions, DeploymentRow, WildcardSubdomainOptions } from './resolvers';
+export type { SpaceCache, SpaceRefusal, SpaceResolution, SpaceResolver } from './types';

package/dist/adapters/space/index.js

@@ -0,0 +1,122 @@
+import { createMemoryCache, isRefusal, refuse } from "./types.js";
+import { authoringPreview, fixedSpace, presentsCredential, verifiedDomain, wildcardSubdomain } from "./resolvers.js";
+import { frameAncestors } from "../../core/auth/domains.js";
+//#region src/adapters/space/index.ts
+var RESOLUTION_PREFIX = "space:resolution:";
+var DOMAINS_PREFIX = "space:domains:";
+/**
+* `getSpaceDeployment`, assembled.
+*
+* Answering "which space is this request for" is the same shape everywhere and the same *rules* everywhere — try
+* the ways a host can name a space, in order; never serve a credentialed request from a shared cache; derive the
+* framing policy from what the space declared; say 404 rather than leaking whether a space exists. What differs
+* between deployments is only where the rows are, which is what a resolver is.
+*
+* ```ts
+* const spaces = createSpaceAdapters({
+*   resolvers: [
+*     authoringPreview({ hosts, resolveGrant: auth.identity.resolveGrant, find: findSpace }),
+*     wildcardSubdomain({ suffix: 'example.app', find: findSpaceBySlug }),
+*     verifiedDomain(findDeploymentByDomain)
+*   ],
+*   cache: redisCache,
+*   frameAncestors: { find: findSpaceDomains, floor: hosts, cache: true }
+* });
+*
+* createServer({ adapters: { ...spaces.adapters, getOfflineData } });
+* ```
+*/
+var createSpaceAdapters = (config) => {
+	const { resolvers, cache, ttlSeconds = 300, cacheKey = (req) => presentsCredential(req) ? void 0 : req.hostname, frameAncestors: frameAncestors$1, decorate, notFound = {
+		code: 404,
+		message: "Space not found"
+	}, onError } = config;
+	const readCache = async (key) => {
+		if (!cache) return;
+		try {
+			const raw = await cache.get(key);
+			return raw === void 0 ? void 0 : JSON.parse(raw);
+		} catch (error) {
+			onError?.(error);
+			return;
+		}
+	};
+	const writeCache = async (key, value) => {
+		if (!cache) return;
+		try {
+			await cache.set(key, JSON.stringify(value), ttlSeconds);
+		} catch (error) {
+			onError?.(error);
+		}
+	};
+	const domainsOf = async (spaceId) => {
+		if (!frameAncestors$1) return [];
+		const key = `${DOMAINS_PREFIX}${spaceId}`;
+		if (frameAncestors$1.cache) {
+			const cached = await readCache(key);
+			if (cached) return cached;
+		}
+		const domains = await frameAncestors$1.find(spaceId);
+		if (frameAncestors$1.cache) await writeCache(key, domains);
+		return domains;
+	};
+	/** Everything that is true of a resolution regardless of which resolver produced it. */
+	const complete = async (resolution, req) => {
+		const decorated = decorate ? {
+			...resolution,
+			...await decorate(resolution, req)
+		} : resolution;
+		return {
+			environment: "main",
+			revision: 0,
+			...decorated,
+			...frameAncestors$1 ? { frameAncestors: frameAncestors(await domainsOf(decorated.spaceId), frameAncestors$1.floor ?? []) } : {}
+		};
+	};
+	const runResolvers = async (req) => {
+		for (const resolve of resolvers) {
+			const answer = await resolve(req);
+			if (answer) return answer;
+		}
+	};
+	const getSpaceDeployment = async (req) => {
+		const key = cacheKey(req);
+		try {
+			if (key !== void 0) {
+				const cached = await readCache(`${RESOLUTION_PREFIX}${key}`);
+				if (cached) return await complete(cached, req);
+			}
+			const answer = await runResolvers(req);
+			if (!answer) return { error: notFound };
+			if (isRefusal(answer)) return { error: answer.refuse };
+			if (key !== void 0 && !answer.authoring) await writeCache(`${RESOLUTION_PREFIX}${key}`, answer);
+			return await complete(answer, req);
+		} catch (error) {
+			onError?.(error, req);
+			return { error: {
+				code: 500,
+				message: "Space could not be resolved"
+			} };
+		}
+	};
+	return {
+		/** Spread into `createServer({ adapters })` beside whatever answers `getOfflineData`. */
+		adapters: { getSpaceDeployment },
+		getSpaceDeployment,
+		/**
+		* Drop what a change made untrue. Both matter the moment an owner edits something through an API: without the
+		* first a domain keeps resolving to the space it used to, and without the second a space stays framable by a
+		* site whose permission was just withdrawn — in both cases until the TTL, which is not a security boundary.
+		*/
+		invalidate: {
+			resolution: async (key) => {
+				await cache?.delete(`${RESOLUTION_PREFIX}${key}`);
+			},
+			domains: async (spaceId) => {
+				await cache?.delete(`${DOMAINS_PREFIX}${spaceId}`);
+			}
+		}
+	};
+};
+//#endregion
+export { authoringPreview, createMemoryCache, createSpaceAdapters, fixedSpace, presentsCredential, refuse, verifiedDomain, wildcardSubdomain };

package/dist/adapters/space/resolvers.d.ts

@@ -0,0 +1,69 @@
+import { SpaceResolution, SpaceResolver } from './types';
+import { GrantOptions, GrantResult } from '../../core/auth/identity';
+import { Environment, SSRCredential, SSRRequest } from '@plitzi/sdk-shared';
+/**
+ * Did this request even try to present a credential?
+ *
+ * Not "is the credential good" — that is `resolveGrant`'s answer, and asking it of every anonymous visitor who
+ * lands on a first-party host would turn them all into 403s. This is the gate before it, and it is also what marks
+ * a request as un-cacheable: the shared resolution cache is keyed by host, and a request carrying a credential can
+ * resolve to a different space than the same host without one.
+ */
+export declare const presentsCredential: (req: SSRRequest) => boolean;
+/** What a deployment row has to be able to say. Anything else on your row stays yours. */
+export interface DeploymentRow {
+    spaceId: number;
+    environment?: Environment;
+    revision?: number | null;
+    credential?: SSRCredential;
+    /** `false` refuses the request outright. A domain that is not proven is not a domain this space answers on. */
+    verified?: boolean;
+}
+/**
+ * The ordinary case: a custom domain someone pointed at this server, resolved through a row that says it was
+ * verified. Returns nothing when the domain is unknown, so a later resolver still gets a turn.
+ */
+export declare const verifiedDomain: (find: (domain: string) => Promise<DeploymentRow | undefined>) => SpaceResolver;
+export interface WildcardSubdomainOptions {
+    /** The domain the sub-domains hang off, with or without a leading dot — `plitzi.app` or `.plitzi.app`. */
+    suffix: string;
+    /** The slug IS the sub-domain. Return nothing for a slug that names no space. */
+    find: (slug: string) => Promise<{
+        spaceId: number;
+        environment?: Environment;
+    } | undefined>;
+}
+/**
+ * Every space reachable at `<slug>.example.com` without anybody configuring a domain for it.
+ *
+ * The point is that it needs no per-space row: the sub-domain is the identifier, so a space is publishable the
+ * moment it exists. It always resolves the live snapshot — a free preview domain that served a pinned revision
+ * would be a second thing to deploy to.
+ */
+export declare const wildcardSubdomain: ({ suffix, find }: WildcardSubdomainOptions) => SpaceResolver;
+export interface AuthoringPreviewOptions {
+    /** The hosts this deployment owns. A credential presented anywhere else is not an authoring session. */
+    hosts: string[];
+    /** Usually `auth.identity.resolveGrant`. */
+    resolveGrant: (req: SSRRequest, options: GrantOptions) => Promise<GrantResult>;
+    /** Confirms the space exists and is readable. Return nothing and the request is a 404. */
+    find: (spaceId: number) => Promise<{
+        spaceId: number;
+        environment?: Environment;
+    } | undefined>;
+    /** Overrides what counts as "tried to present a credential". Defaults to {@link presentsCredential}. */
+    presented?: (req: SSRRequest) => boolean;
+}
+/**
+ * An author looking at their own space through a builder, rather than a visitor being served.
+ *
+ * Put this FIRST. It engages only when a credential is presented on a host this deployment owns, and once it has,
+ * a bad credential is a refusal rather than a fall-through — a request that tried to act for a space and failed
+ * must not then be served as an anonymous visitor of whatever else that host resolves to.
+ *
+ * `skipOrigin` is deliberate: a preview is loaded as a document, and a top-level navigation carries no `Origin`.
+ * It does not skip the domain binding, which is the part that matters.
+ */
+export declare const authoringPreview: ({ hosts, resolveGrant, find, presented }: AuthoringPreviewOptions) => SpaceResolver;
+/** A space this server always serves, whatever the host — a single-space deployment, or the last word in a chain. */
+export declare const fixedSpace: (resolution: SpaceResolution) => SpaceResolver;

package/dist/adapters/space/resolvers.js

@@ -0,0 +1,79 @@
+import { refuse } from "./types.js";
+//#region src/adapters/space/resolvers.ts
+/**
+* Did this request even try to present a credential?
+*
+* Not "is the credential good" — that is `resolveGrant`'s answer, and asking it of every anonymous visitor who
+* lands on a first-party host would turn them all into 403s. This is the gate before it, and it is also what marks
+* a request as un-cacheable: the shared resolution cache is keyed by host, and a request carrying a credential can
+* resolve to a different space than the same host without one.
+*/
+var presentsCredential = (req) => Boolean(req.query["access-token"]) || Boolean(req.headers.authorization);
+/**
+* The ordinary case: a custom domain someone pointed at this server, resolved through a row that says it was
+* verified. Returns nothing when the domain is unknown, so a later resolver still gets a turn.
+*/
+var verifiedDomain = (find) => {
+	return async (req) => {
+		const row = await find(req.hostname);
+		if (!row) return;
+		if (row.verified === false) return refuse(404, "Domain not verified");
+		const { spaceId, environment, credential } = row;
+		return {
+			spaceId,
+			...environment ? { environment } : {},
+			revision: row.revision ?? 0,
+			...credential ? { credential } : {}
+		};
+	};
+};
+/**
+* Every space reachable at `<slug>.example.com` without anybody configuring a domain for it.
+*
+* The point is that it needs no per-space row: the sub-domain is the identifier, so a space is publishable the
+* moment it exists. It always resolves the live snapshot — a free preview domain that served a pinned revision
+* would be a second thing to deploy to.
+*/
+var wildcardSubdomain = ({ suffix, find }) => {
+	const dotted = suffix.startsWith(".") ? suffix : `.${suffix}`;
+	return async (req) => {
+		if (!req.hostname.endsWith(dotted)) return;
+		const slug = req.hostname.slice(0, -dotted.length);
+		if (!slug || slug.includes(".")) return;
+		const space = await find(slug);
+		return space ? {
+			...space,
+			revision: 0
+		} : void 0;
+	};
+};
+/**
+* An author looking at their own space through a builder, rather than a visitor being served.
+*
+* Put this FIRST. It engages only when a credential is presented on a host this deployment owns, and once it has,
+* a bad credential is a refusal rather than a fall-through — a request that tried to act for a space and failed
+* must not then be served as an anonymous visitor of whatever else that host resolves to.
+*
+* `skipOrigin` is deliberate: a preview is loaded as a document, and a top-level navigation carries no `Origin`.
+* It does not skip the domain binding, which is the part that matters.
+*/
+var authoringPreview = ({ hosts, resolveGrant, find, presented = presentsCredential }) => {
+	return async (req) => {
+		if (!hosts.includes(req.hostname) || !presented(req)) return;
+		const result = await resolveGrant(req, { skipOrigin: true });
+		if (!result.ok) return refuse(403, "Access Not Authorized");
+		const space = await find(result.grant.spaceId);
+		if (!space) return refuse(404, "Space not found");
+		return {
+			...space,
+			revision: 0,
+			authoring: true
+		};
+	};
+};
+/** A space this server always serves, whatever the host — a single-space deployment, or the last word in a chain. */
+var fixedSpace = (resolution) => {
+	return () => Promise.resolve(resolution);
+};
+//#endregion
+export { authoringPreview, fixedSpace, presentsCredential, verifiedDomain, wildcardSubdomain };

package/dist/adapters/space/space.test.d.ts

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