@stacksjs/sites 0.71.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @stacksjs/sites
+
+Request-level multi-site tenancy: one Stacks app serving many public web
+properties, each resolved from the request's Host header.
+
+A host resolves in this order:
+
+1. exact match on a **verified** `site_domains.domain` row (custom domains)
+2. `{subdomain}.{config.sites.baseDomain}` matching `sites.subdomain`
+3. a configured platform host (the app itself) - no site, never 404'd
+4. nothing - null, or 404 when `config.sites.strict` is on
+
+## The two channels
+
+- **API / bun-router:** the `siteResolver` middleware stamps `request.site`
+  and the ambient AsyncLocalStorage context (`currentSite()`, `requireSite()`).
+- **STX pages:** ALS does not survive into stx-serve's render. The serving
+  layer stashes `toSiteSnapshot(site)` on the request-context snapshot, and
+  `<script server>` blocks read `requestContext.site()`. Never call
+  `currentSite()` from an stx server script.
+
+## Scoping is explicit
+
+There is no automatic global scope, on purpose: generated `Model.where()`
+statics offer no interception point, and an implicit ALS scope silently
+vanishes in queue workers and CLI runs - exactly where a missing scope becomes
+a cross-tenant leak. Instead:
+
+- data-layer functions take `siteId` as a required argument; the route
+  boundary resolves it once via `requireSite()`
+- `forSite(qb)` scopes a query builder to the ambient site
+- `siteOwnership()` plugs into `model.ownership` so admin `useApi` routes are
+  restricted to sites the caller's active team owns
+
+Deploy-level tenancy (`cloud.attachTo`) is a different axis: that is many apps
+on one box. This is many sites in one app.

package/dist/context.d.ts

@@ -0,0 +1,34 @@
+import type { SiteContext } from './types';
+/** Run `fn` with `site` as the ambient site context. */
+export declare function runWithSite<T>(site: SiteContext | null, fn: () => T): T;
+/**
+ * Set the ambient site for the remainder of the current async scope.
+ *
+ * For middleware pipelines that cannot wrap the downstream handler in a
+ * callback. `enterWith` binds to the current execution context, which the
+ * router's per-request scope already isolates.
+ */
+export declare function setCurrentSite(site: SiteContext | null): void;
+/** The resolved site, or undefined outside any site scope (jobs, CLI, platform hosts). */
+export declare function currentSite(): SiteContext | undefined;
+/** The resolved site's id, or undefined. */
+export declare function currentSiteId(): number | undefined;
+/**
+ * The resolved site, or throw 404.
+ *
+ * The route boundary calls this exactly once and passes `site.id` down
+ * explicitly - data-layer functions take `siteId` as a required argument
+ * rather than defaulting to ambient context, so a forgotten scope is a
+ * compile error, not a cross-tenant query.
+ */
+export declare function requireSite(): SiteContext;
+/**
+ * Thrown when a handler that only makes sense on a tenant site runs without
+ * one - an unknown host, or a platform host hitting a site-only route.
+ * Carries `status: 404` so the router's error mapping answers Not Found
+ * rather than 500: an unknown host is the visitor's dead end, not our bug.
+ */
+export declare class SiteNotResolvedError extends Error {
+  readonly status: number;
+  constructor(message?: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export type { SiteSnapshotShape } from './snapshot';
+export type { HostKind, ResolvedSitesOptions, SiteContext, SiteStore } from './types';
+export {
+  currentSite,
+  currentSiteId,
+  requireSite,
+  runWithSite,
+  setCurrentSite,
+  SiteNotResolvedError,
+} from './context';
+export { default as siteResolver } from './middleware';
+export {
+  classifyHost,
+  clearSiteCache,
+  databaseSiteStore,
+  isPlatformHost,
+  normalizeHost,
+  requestHost,
+  resolveSiteByHost,
+  sitesOptions,
+} from './resolver';
+export { forSite, siteOwnership } from './scoping';
+export { toSiteSnapshot } from './snapshot';

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+export{R as toSiteSnapshot,c as sitesOptions,n as siteResolver,C as siteOwnership,S as setCurrentSite,i as runWithSite,H as resolveSiteByHost,s as requireSite,d as requestHost,u as normalizeHost,h as isPlatformHost,v as forSite,x as databaseSiteStore,r as currentSiteId,o as currentSite,m as clearSiteCache,l as classifyHost,p as SiteNotResolvedError};

package/dist/middleware.d.ts

@@ -0,0 +1,12 @@
+import { Middleware } from '@stacksjs/router';
+declare const __dtsx_default_export__: Middleware;
+/**
+ * Resolve the request's site from its Host header and publish it two ways:
+ * as `request.site` for handlers that hold the request, and as the ambient
+ * ALS context for model/query code downstream (`currentSite()`).
+ *
+ * Register under the `site` alias in `app/Middleware.ts` and attach to the
+ * route groups that serve tenant traffic. With `config.sites.strict`, an
+ * unknown host 404s here; platform hosts always pass with a null site.
+ */
+export default __dtsx_default_export__;

package/dist/resolver.d.ts

@@ -0,0 +1,35 @@
+import type { HostKind, ResolvedSitesOptions, SiteContext, SiteStore } from './types';
+/**
+ * Lowercase, strip the port and any trailing dot. `Host: StMarks.CampusHQ.com:443.`
+ * and `stmarks.campushq.com` are the same site; DNS names are case-insensitive
+ * and the port is transport, not identity.
+ *
+ * IDN hosts arrive from the browser already punycoded (`xn--...`), so domains
+ * must be STORED punycoded; this function does not transcode.
+ */
+export declare function normalizeHost(raw: string | null | undefined): string;
+/** `config.sites` with every field resolved to a concrete value. */
+export declare function sitesOptions(): ResolvedSitesOptions;
+/**
+ * Pure classification of a normalized host. Platform wins over subdomain so
+ * the app's own hosts (`www.<baseDomain>`, the apex itself) can never resolve
+ * as tenants even when they syntactically look like one.
+ */
+export declare function classifyHost(host: string, options: Pick<ResolvedSitesOptions, 'baseDomain' | 'platformHosts'>): HostKind;
+/**
+ * The Host header this request should be judged by. Prefers the proxy's
+ * `X-Forwarded-Host` when configured to (both the stx views proxy and the rpx
+ * gateway forward it); otherwise the connection's own Host.
+ */
+export declare function requestHost(headers: Headers, options: Pick<ResolvedSitesOptions, 'trustProxyHost'>): string;
+export declare function clearSiteCache(): void;
+/**
+ * Host -> site, cached. Null means "no such site": platform hosts, unknown
+ * hosts, and disabled multi-site all land there - `strict` decides what the
+ * caller does about unknown ones.
+ */
+export declare function resolveSiteByHost(rawHost: string, store?: SiteStore, options?: ResolvedSitesOptions): Promise<SiteContext | null>;
+/** Is this host the app itself rather than a tenant site? */
+export declare function isPlatformHost(rawHost: string, options?: ResolvedSitesOptions): boolean;
+/** The default store: `sites` + `site_domains` via the query builder. */
+export declare const databaseSiteStore: SiteStore;

package/dist/scoping.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Scope a query to the ambient site. EXPLICIT by design: the generated
+ * `Model.where()` statics have no interception point for an automatic global
+ * scope, and an ALS-driven implicit one would silently vanish in queue
+ * workers, cron and the CLI - exactly where a missing scope becomes a
+ * cross-tenant leak. A visible `forSite(...)` is grep-able and auditable.
+ */
+// eslint-disable-next-line pickier/no-unused-vars -- `args` names the variadic in the structural type only
+export declare function forSite<QB extends { where: (...args: any[]) => QB }>(qb: QB, column?: string, siteId?: number | undefined): QB;
+/**
+ * `model.ownership` config for ADMIN surfaces (dashboard editing of
+ * site-scoped content through `useApi` routes): the authenticated user may
+ * touch rows belonging to any site their active team owns. Public site reads
+ * never ride this - they go through dedicated routes that call
+ * `requireSite()` and scope by the request's host instead.
+ */
+export declare function siteOwnership(): {
+  field: string
+  resolve: (user: unknown, req: unknown) => Promise<number[] | null>
+};

package/dist/snapshot.d.ts

@@ -0,0 +1,15 @@
+import type { SiteContext } from './types';
+export declare function toSiteSnapshot(site: SiteContext | null | undefined): SiteSnapshotShape | null;
+/**
+ * The shape the stx serving layer stashes on the request-context snapshot
+ * (`RequestContextSnapshot.site` in `@stacksjs/config`), which is how
+ * `<script server>` blocks see the site - ALS does not survive into
+ * stx-serve's render, so this is the one channel that works there.
+ */
+export declare interface SiteSnapshotShape {
+  id: number
+  uuid?: string
+  name?: string
+  subdomain?: string
+  settings?: Record<string, unknown>
+}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What the resolver hands the rest of the request: enough to scope queries,
+ * theme a render, and build absolute URLs - without another DB round trip.
+ */
+export declare interface SiteContext {
+  id: number
+  uuid: string
+  name: string
+  subdomain: string
+  host: string
+  teamId: number | null
+  status: string
+  settings: Record<string, unknown>
+}
+/** The pieces of `config.sites` the resolver actually reads, resolved to values. */
+export declare interface ResolvedSitesOptions {
+  enabled: boolean
+  baseDomain: string
+  platformHosts: string[]
+  strict: boolean
+  trustProxyHost: boolean
+  cacheTtlSeconds: number
+}
+/**
+ * The storage seam the resolver reads through, injectable so the pure
+ * resolution pipeline is testable without a database. The default store
+ * queries `sites` / `site_domains` via `@stacksjs/database`.
+ */
+export declare interface SiteStore {
+  byDomain: (domain: string) => Promise<SiteContext | null>
+  bySubdomain: (subdomain: string) => Promise<SiteContext | null>
+}
+export type HostKind = | { kind: 'platform' }
+    | { kind: 'subdomain', subdomain: string }
+    | { kind: 'custom', domain: string }

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@stacksjs/sites",
+  "type": "module",
+  "version": "0.71.1",
+  "description": "The Stacks multi-site (request-level tenancy) functionality.",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/sites#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/sites"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "multi-site",
+    "tenancy",
+    "domains",
+    "stacks"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "bun": "./dist/*.js",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "bun": "./dist/*.js",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@stacksjs/auth": "0.71.1",
+    "@stacksjs/config": "0.71.1",
+    "@stacksjs/database": "0.71.1",
+    "@stacksjs/error-handling": "0.71.1",
+    "@stacksjs/router": "0.71.1",
+    "better-dx": "^0.2.23"
+  },
+  "sideEffects": false
+}