@warpgogol/werkstatt-shared 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/werkstatt-shared",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "private": false,
   "type": "module",
   "engines": {
@@ -250,6 +250,10 @@
       "types": "./src/share/middleware/language-redirect.ts",
       "default": "./src/share/middleware/language-redirect.ts"
     },
+    "./share/middleware/access-protection": {
+      "types": "./src/share/middleware/access-protection.ts",
+      "default": "./src/share/middleware/access-protection.ts"
+    },
     "./share/offer-capacity": {
       "types": "./src/share/offer-capacity.ts",
       "default": "./src/share/offer-capacity.ts"
@@ -318,6 +322,14 @@
       "types": "./src/share/shared-context.ts",
       "default": "./src/share/shared-context.ts"
     },
+    "./share/slug": {
+      "types": "./src/share/slug/index.ts",
+      "default": "./src/share/slug/index.ts"
+    },
+    "./share/routes/template-filter": {
+      "types": "./src/share/routes/template-filter.ts",
+      "default": "./src/share/routes/template-filter.ts"
+    },
     "./share/string-utils": {
       "types": "./src/share/string-utils.ts",
       "default": "./src/share/string-utils.ts"
@@ -1349,14 +1361,17 @@
   ],
   "dependencies": {
     "@lordicon/element": "^2.3.1",
-    "@noble/ed25519": "^3.1.0",
+    "@warpgogol/werkstatt": "*",
     "ajv": "^8.20.0",
     "bs58": "^6.0.0",
+    "@sindresorhus/slugify": "^3.0.0",
+    "cyrillic-to-translit-js": "^3.2.1",
     "expr-eval": "^2.0.2",
-    "gray-matter": "^4.0.3",
+    "github-slugger": "^2.0.0",
     "hls.js": "^1.6.16",
     "lenis": "^1.3.25",
     "plyr": "^3.8.4",
+    "gray-matter": "^4.0.3",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
@@ -1367,7 +1382,7 @@
     "@astrojs/markdown-remark": "^7.0.0",
     "@cloudflare/workers-types": "^5.20260801.1",
     "@types/node": "^24.0.0",
-    "@warpgogol/werkstatt": "1.4.0",
+    "@warpgogol/werkstatt": "*",
     "astro": "^7.2.0",
     "eslint": "^10.8.0",
     "fast-check": "^4.9.0",

package/src/checks/index.ts

@@ -16,6 +16,7 @@ export {
   passResult,
   failResult,
   resultFromViolations,
+  formatCounts,
 } from "./result-helpers.ts";
 
 export * from "./suppressions-config.ts";

package/src/checks/result-helpers.ts

@@ -16,16 +16,55 @@ ruleId = command; diagnosticsResult takes rich Diagnostic[] with registered ids.
 </CHANGE_SUMMARY>
 */
 
-import type { CheckResult, Diagnostic, KernelCommandResult } from "@warpgogol/werkstatt/kernel";
+import type {
+  CheckResult,
+  Diagnostic,
+  KernelCommandResult,
+  KernelNextStep,
+} from "@warpgogol/werkstatt/kernel";
+
+function defaultFailNextSteps(command: string): KernelNextStep[] {
+  return [
+    {
+      action: `Fix the error diagnostics reported by ${command} above, then re-run the pipeline`,
+      kind: "required",
+    },
+  ];
+}
+
+/**
+ * Format error/warning counts with proper pluralization and zero-omission.
+ *
+ * - `0, 0` → `""` (empty string — caller should omit)
+ * - `1, 0` → `"1 error"`
+ * - `0, 1` → `"1 warning"`
+ * - `2, 0` → `"2 errors"`
+ * - `2, 1` → `"2 errors, 1 warning"`
+ */
+export function formatCounts(errors: number, warnings: number): string {
+  const parts: string[] = [];
+  if (errors > 0) {
+    parts.push(`${errors} error${errors === 1 ? "" : "s"}`);
+  }
+  if (warnings > 0) {
+    parts.push(`${warnings} warning${warnings === 1 ? "" : "s"}`);
+  }
+  return parts.join(", ");
+}
 
 /**
  * RFC-0203: canonical result builder. Migrated checks emit `Diagnostic[]` with
  * registered rule ids instead of bare strings. Exit code is 1 when any
  * diagnostic is an error; warnings and info do not fail the pipeline.
+ *
+ * When `nextSteps` are not provided and the result has errors, a default
+ * agent-actionable nextStep is emitted: "Fix the error diagnostics … then
+ * re-run the pipeline".
  */
 export function diagnosticsResult(
   command: string,
   diagnostics: Diagnostic[],
+  nextSteps?: KernelNextStep[],
 ): KernelCommandResult<CheckResult> {
   const summary = {
     error: diagnostics.filter((d) => d.severity === "error").length,
@@ -34,10 +73,14 @@ export function diagnosticsResult(
   };
   const status: CheckResult["status"] =
     summary.error > 0 ? "fail" : summary.warning > 0 ? "warn" : "pass";
+  const resolvedNextSteps =
+    nextSteps ?? (summary.error > 0 ? defaultFailNextSteps(command) : undefined);
+  const counts = formatCounts(summary.error, summary.warning);
   return {
     data: { command, status, diagnostics, summary },
     exitCode: summary.error > 0 ? 1 : 0,
-    summary: `${command}: ${summary.error} error(s), ${summary.warning} warning(s)`,
+    summary: counts ? `[${command}] ${counts}` : `[${command}]`,
+    nextSteps: resolvedNextSteps,
   };
 }
 
@@ -58,11 +101,16 @@ function emptySummary(): CheckResult["summary"] {
  * Canonical success result. RFC-0203: emits an empty `CheckResult` (no
  * diagnostics) rather than the legacy `{ command, status, violations }` shape.
  */
-export function passResult(command: string, summary?: string): KernelCommandResult<CheckResult> {
+export function passResult(
+  command: string,
+  summary?: string,
+  nextSteps?: KernelNextStep[],
+): KernelCommandResult<CheckResult> {
   return {
     data: { command, status: "pass", diagnostics: [], summary: emptySummary() },
     exitCode: 0,
-    summary: summary ?? `${command}: OK`,
+    summary: summary ?? `[${command}] OK`,
+    nextSteps,
   };
 }
 
@@ -70,10 +118,14 @@ export function passResult(command: string, summary?: string): KernelCommandResu
  * Canonical failure result — always exits 1 (preserving the historical
  * failResult contract). RFC-0203: violation strings become error Diagnostics
  * keyed by the command name.
+ *
+ * When `nextSteps` are not provided, a default agent-actionable nextStep is
+ * emitted: "Fix the error diagnostics … then re-run the pipeline".
  */
 export function failResult(
   command: string,
   violations: string[],
+  nextSteps?: KernelNextStep[],
 ): KernelCommandResult<CheckResult> {
   const diagnostics = violationsToDiagnostics(command, violations);
   return {
@@ -84,7 +136,8 @@ export function failResult(
       summary: { error: diagnostics.length, warning: 0, info: 0 },
     },
     exitCode: 1,
-    summary: `${command}: ${violations.length} violation(s)`,
+    summary: `[${command}] ${violations.length} violation${violations.length === 1 ? "" : "s"}`,
+    nextSteps: nextSteps ?? defaultFailNextSteps(command),
   };
 }
 
@@ -97,6 +150,7 @@ export function failResult(
 export function resultFromViolations(
   command: string,
   violations: string[],
+  nextSteps?: KernelNextStep[],
 ): KernelCommandResult<CheckResult> {
-  return violations.length > 0 ? failResult(command, violations) : passResult(command);
+  return violations.length > 0 ? failResult(command, violations, nextSteps) : passResult(command);
 }

package/src/checks/suppressions-config.ts

@@ -17,7 +17,32 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { parse as parseYaml } from "yaml";
-import type { Finding } from "@syrokomskyi/axiom-study";
+
+/**
+ * Minimal Finding shape matching @syrokomskyi/axiom-study's Finding interface.
+ * Defined locally so the package typechecks without axiom-study installed.
+ * See share/types/axiom-study.d.ts for the full canonical declaration.
+ */
+interface Finding {
+  findingId: string;
+  semanticFingerprint: { algorithm: "sha256"; digest: string; size: number; mediaType: string };
+  methodologyId: string;
+  ruleId: string;
+  affectedSubjectId: string;
+  title: string;
+  severity: "info" | "low" | "medium" | "high" | "critical";
+  evidence: Array<{
+    evidenceRef: {
+      artifactId: string;
+      rootDigest: { algorithm: "sha256"; digest: string; size: number; mediaType: string };
+      schema: string;
+    };
+    selector: string;
+    evidenceClass: string;
+  }>;
+  uncertainty: unknown[];
+  extension: Record<string, unknown>;
+}
 
 export const suppressionRuleSchema = z.object({
   ruleId: z.string().min(1),

package/src/content/system-manifest.ts

@@ -9,6 +9,7 @@ Stack-agnostic utility used by both engine and site plugin (RFC-0868).</purpose>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0868: extracted from werkstatt-site/src/content/system-manifest.ts.</item>
+  <item>RFC-0911: add seo?.anchorText?.extraStopPhrases for anchor-text stop-list extension.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -101,6 +102,13 @@ export interface SystemManifest {
       swapOrder?: boolean;
     };
   };
+  /** RFC-0911: SEO validator configuration extension point. */
+  seo?: {
+    anchorText?: {
+      /** Added to the built-in de/uk stop-list. */
+      extraStopPhrases?: Record<string, string[]>;
+    };
+  };
 }
 
 export interface SystemManifestLoadResult {

package/src/ontology/archetypes/index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "totalCount": 58,
+  "totalCount": 59,
   "entries": [
     {
       "id": "approach",
@@ -218,6 +218,18 @@
       "sourceFile": "packages/werkstatt-site/src/domain/ontology/archetypes/components/footer-promo.yaml",
       "layer": "component"
     },
+    {
+      "id": "gratitude",
+      "displayName": "Gratitude",
+      "semanticRole": "client-gratitude",
+      "version": "1.0.0",
+      "layoutHint": "card-grid",
+      "acceptedCosmicNames": [
+        "Gonggong"
+      ],
+      "sourceFile": "packages/werkstatt-site/src/domain/ontology/archetypes/sections/gratitude.yaml",
+      "layer": "section"
+    },
     {
       "id": "hero",
       "displayName": "Hero",
@@ -704,6 +716,7 @@
     "article-index",
     "audience-self-identification",
     "breadcrumbs",
+    "client-gratitude",
     "client-ownership-disclosure",
     "consent-gated-chat-launcher",
     "credits-gallery",
@@ -777,6 +790,7 @@
     "Elara": "@warpgogol/werkstatt-site/ui/sections/dynamic-status-block",
     "Atlas": "@warpgogol/werkstatt-site/ui/sections/faq-list",
     "Dione": "@warpgogol/werkstatt-site/ui/sections/final-cta",
+    "Gonggong": "@warpgogol/werkstatt-site/ui/sections/gratitude",
     "Europa": "@warpgogol/werkstatt-site/ui/sections/hero",
     "Phobos": "@warpgogol/werkstatt-site/ui/sections/hero-decision-card",
     "Ganymede": "@warpgogol/werkstatt-site/ui/sections/impact",
@@ -854,6 +868,7 @@
     "dynamic-status-block": "Elara",
     "faq-list": "Atlas",
     "final-cta": "Dione",
+    "gratitude": "Gonggong",
     "hero": "Europa",
     "hero-decision-card": "Phobos",
     "impact": "Ganymede",
@@ -935,6 +950,7 @@
     "Elara": "data-driven-status-indicator",
     "Atlas": "approach",
     "Dione": "final-cta",
+    "Gonggong": "client-gratitude",
     "Europa": "hero",
     "Phobos": "hero",
     "Ganymede": "impact",

package/src/ontology/schemas/page-entry.ts

@@ -66,14 +66,12 @@ const visibilityExprSchema: z.ZodType<unknown> = z.lazy(() =>
 export const BlockEntrySchema = z
   .object({
     /**
-     * Optional stable block identifier for analytics, anchor links, and
-     * block-level attribution. Must be kebab-case when provided.
-     * page.block.validate enforces uniqueness within a page.
+     * Mandatory stable block identifier for analytics, anchor links, and
+     * block-level attribution. Must be kebab-case. RFC-0914 makes this required.
+     * page.block.validate enforces uniqueness within a page (B-05).
+     * page.blocks.extract.validate enforces presence and format (BLOCK-ID-MISSING, BLOCK-ID-INVALID).
      */
-    id: z
-      .string()
-      .regex(/^[a-z0-9-]+$/, "Block id must be kebab-case")
-      .optional(),
+    id: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "Block id must be kebab-case"),
 
     /**
      * Cosmic name identifying the section/component for this block.

package/src/ontology/schemas/system/manifest.ts

@@ -17,6 +17,7 @@ import { systemSharedContextSchema, systemGrowthSchema } from "./growth.ts";
 import { systemReleaseSchema } from "./release.ts";
 import { systemTextSchema } from "./text.ts";
 import { systemIntegrationsSchema } from "./integrations.ts";
+import { systemVerificationSchema } from "./verification.ts";
 import { semanticPageTypeSchema, articleMetadataSchema, pageOutputSchema } from "./page-output.ts";
 
 /**
@@ -482,6 +483,13 @@ export const systemManifestSchema = z.object({
         .optional(),
     })
     .optional(),
+
+  /**
+   * Search engine verification config (RFC-0909).
+   * Declares per-engine verification method and token.
+   * When absent, search.verification.validate emits SEARCH-VERIFY-01.
+   */
+  verification: systemVerificationSchema.optional(),
 });
 
 export type SystemManifest = z.infer<typeof systemManifestSchema>;

package/src/ontology/schemas/system/verification.ts

@@ -0,0 +1,40 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Verification block schema (RFC-0909) for the system manifest.
+Declares per-search-engine verification method and token for Google Search Console.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0909: initial verification schema for search engine verification surface.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+/**
+ * The `verification:` block in src/content/system.md. Declares per-search-engine
+ * verification method and token so that search.verification.validate can enforce
+ * the declaration and the layout can emit the google-site-verification meta tag.
+ *
+ * Example src/content/system.md verification block:
+ *   verification:
+ *     google:
+ *       method: dns-txt
+ *       token: google-site-verification=abc123...
+ */
+export const systemVerificationSchema = z.object({
+  google: z
+    .object({
+      method: z.enum(["dns-txt", "meta-tag"]),
+      /**
+       * dns-txt: full TXT value "google-site-verification=...".
+       * meta-tag: content attribute of the google-site-verification meta tag.
+       */
+      token: z.string().min(1),
+    })
+    .optional(),
+});
+
+export type SystemVerification = z.infer<typeof systemVerificationSchema>;

package/src/passport/sign.ts

@@ -1,5 +1,5 @@
 /* <MODULE_CONTRACT>
-<purpose>Facilitates Ed25519 key generation, signing, and verification for verifiable credentials.</purpose>
+<purpose>Facilitates Ed25519 key generation, signing, and verification for verifiable credentials via shared signing core (RFC-0921).</purpose>
 <non-goals>
   <item>Do not handle raw key storage or management.</item>
   <item>Do not perform network operations or external API calls.</item>
@@ -8,6 +8,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+  <item>RFC-0921: delegate Ed25519 sign/verify/keygen to shared signing core (@warpgogol/werkstatt/signing). Remove @noble/ed25519 import.</item>
 </CHANGE_SUMMARY> */
 
 /**
@@ -24,8 +25,14 @@
  * - This module never logs, writes, or returns private key material.
  */
 
-import * as ed from "@noble/ed25519";
 import bs58 from "bs58";
+import {
+  generateKeyPair as signingGenerateKeyPair,
+  signBytes as signingSignBytes,
+  verifyBytes as signingVerifyBytes,
+  fromHex,
+  toHex,
+} from "@warpgogol/werkstatt/signing";
 import type { VCProof, VerifiableCredential } from "./schema.ts";
 
 // ---------------------------------------------------------------------------
@@ -90,12 +97,11 @@ export async function generateKeypair(): Promise<{
   publicKeyBytes: Uint8Array;
   publicKeyMultibase: string;
 }> {
-  const privateKeyBytes = ed.utils.randomSecretKey();
-  const publicKeyBytes = await ed.getPublicKeyAsync(privateKeyBytes);
+  const keyPair = await signingGenerateKeyPair();
   return {
-    privateKeyHex: Buffer.from(privateKeyBytes).toString("hex"),
-    publicKeyBytes,
-    publicKeyMultibase: toMultibase(publicKeyBytes),
+    privateKeyHex: toHex(keyPair.privateKey),
+    publicKeyBytes: keyPair.publicKey,
+    publicKeyMultibase: toMultibase(keyPair.publicKey),
   };
 }
 
@@ -110,7 +116,7 @@ export async function generateKeypair(): Promise<{
  * @param privateKeyHex — 32-byte Ed25519 private key as hex (from env secret)
  * @param verificationMethod — DID key reference (e.g. "did:web:example.org#key-v1")
  */
-// @ai-invariant: signCredential uses @noble/ed25519. Private keys arrive
+// @ai-invariant: signCredential uses the shared signing core (RFC-0921). Private keys arrive
 // exclusively as hex env vars — never logged, written to disk, or returned.
 // The signed output is a W3C VC with Ed25519Signature2020 proof.
 
@@ -119,9 +125,9 @@ export async function signCredential(
   privateKeyHex: string,
   verificationMethod: string,
 ): Promise<VCProof> {
-  const privateKeyBytes = new Uint8Array(Buffer.from(privateKeyHex, "hex"));
+  const privateKeyBytes = fromHex(privateKeyHex);
   const message = credentialBytes(subject);
-  const signatureBytes = await ed.signAsync(message, privateKeyBytes);
+  const signatureBytes = await signingSignBytes(privateKeyBytes, message);
 
   return {
     type: "Ed25519Signature2020",
@@ -153,7 +159,7 @@ export async function verifyCredential(
     const publicKeyBytes = fromMultibase(publicKeyMultibase);
     const signatureBytes = fromMultibase(proof.proofValue);
     const message = credentialBytes(subject);
-    return await ed.verifyAsync(signatureBytes, message, publicKeyBytes);
+    return await signingVerifyBytes(publicKeyBytes, message, signatureBytes);
   } catch {
     return false;
   }
@@ -173,8 +179,8 @@ export async function verifyCredential(
  * @param message       — canonical bytes to sign
  */
 export async function signBytes(privateKeyHex: string, message: Uint8Array): Promise<string> {
-  const privateKeyBytes = new Uint8Array(Buffer.from(privateKeyHex, "hex"));
-  const signatureBytes = await ed.signAsync(message, privateKeyBytes);
+  const privateKeyBytes = fromHex(privateKeyHex);
+  const signatureBytes = await signingSignBytes(privateKeyBytes, message);
   return toMultibase(signatureBytes);
 }
 
@@ -190,7 +196,7 @@ export async function verifyBytes(
   try {
     const publicKeyBytes = fromMultibase(publicKeyMultibase);
     const signatureBytes = fromMultibase(signatureMultibase);
-    return await ed.verifyAsync(signatureBytes, message, publicKeyBytes);
+    return await signingVerifyBytes(publicKeyBytes, message, signatureBytes);
   } catch {
     return false;
   }

package/src/share/middleware/access-protection.ts

@@ -0,0 +1,174 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0899: Runtime access protection middleware for dev/alt subdomains. Checks Host header and requires Basic Auth with a 4-digit PIN for dev.* and alt.* hosts. Sets X-Robots-Tag headers to prevent indexing.</purpose>
+<keywords>middleware, access-protection, basic-auth, pin, dev, alt, RFC-0899</keywords>
+<responsibilities>
+  <item>Check Host header against dev.* and alt.* patterns — pass through for main domain.</item>
+  <item>Require Basic Auth (username: warp, password: ACCESS_PIN env var) for dev/alt hosts.</item>
+  <item>Set X-Robots-Tag: noindex, nofollow, noai, noimageai on ALL dev/alt responses (including 401).</item>
+  <item>Use constant-time string comparison for auth check to prevent timing attacks.</item>
+  <item>Pass through when ACCESS_PIN is unset (allows new sites before protection is configured).</item>
+</responsibilities>
+<non-goals>
+  <item>Do not modify the HTML response body — only headers and access gating.</item>
+  <item>Do not activate for the main/production domain, even if the PIN secret is set on the main Worker.</item>
+  <item>Do not use Node.js-specific APIs (Buffer, crypto.timingSafeEqual) — runs in Cloudflare Workers runtime.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0899: Initial access protection middleware for dev/alt subdomains.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { defineMiddleware } from "astro:middleware";
+
+const NOINDEX_HEADER = "noindex, nofollow, noai, noimageai";
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * Returns true if both strings are equal, false otherwise.
+ * Always processes the full length of both strings regardless of match status.
+ */
+function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+/**
+ * Check if a host is a dev or alt subdomain.
+ */
+function isDevOrAltHost(host: string): boolean {
+  return host.startsWith("dev.") || host.startsWith("alt.");
+}
+
+/**
+ * RFC-0899: Check access protection for a request. Called from the Worker entry point
+ * (worker.ts) before passing to the Astro handler. This is necessary because Astro
+ * middleware does not run for prerendered static pages (output: "static") — the
+ * Cloudflare adapter serves them from the ASSETS binding directly.
+ *
+ * Returns a 401 Response if access is denied, or null if the request should pass through.
+ * For dev/alt hosts with no PIN set, returns null (pass through) — caller should add
+ * X-Robots-Tag header to the response.
+ *
+ * @param request - The incoming Request
+ * @param env - The Worker env object (contains ACCESS_PIN)
+ * @returns 401 Response if denied, null if pass through
+ */
+export function checkAccessProtection(
+  request: Request,
+  env: Record<string, unknown>,
+): Response | null {
+  const host = request.headers.get("host") ?? "";
+  if (!isDevOrAltHost(host)) return null;
+
+  const pin = (env.ACCESS_PIN as string | undefined) ?? undefined;
+
+  // No PIN set — allow access (caller should add X-Robots-Tag)
+  if (!pin) return null;
+
+  // Check Basic Auth
+  const auth = request.headers.get("authorization") ?? "";
+  const expected = `Basic ${btoa(`warp:${pin}`)}`;
+
+  if (auth && constantTimeEqual(auth, expected)) {
+    return null; // Authenticated — pass through
+  }
+
+  // Not authenticated — challenge
+  return new Response("Authentication required", {
+    status: 401,
+    headers: {
+      "WWW-Authenticate": 'Basic realm="Staging Access"',
+      "X-Robots-Tag": NOINDEX_HEADER,
+    },
+  });
+}
+
+/**
+ * RFC-0899: Add X-Robots-Tag header to a response for dev/alt subdomains.
+ * Called after the Astro handler returns a response, if the host is dev/alt.
+ *
+ * @param response - The response to modify
+ * @returns A new response with X-Robots-Tag added (if dev/alt host)
+ */
+export function addNoIndexHeaderIfNeeded(request: Request, response: Response): Response {
+  const host = request.headers.get("host") ?? "";
+  if (!isDevOrAltHost(host)) return response;
+
+  const headers = new Headers(response.headers);
+  headers.set("X-Robots-Tag", NOINDEX_HEADER);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+// cloudflare:workers is only available in the Cloudflare Workers runtime.
+// In Astro build (Node.js) the static import fails — resolve lazily so the
+// middleware still loads; ACCESS_PIN is undefined in build (no runtime binding).
+async function resolveAccessPin(): Promise<string | undefined> {
+  try {
+    const { env } = await import("cloudflare:workers");
+    return (env.ACCESS_PIN as string | undefined) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * RFC-0899: Access protection middleware for dev/alt subdomains.
+ *
+ * At runtime, checks the Host header:
+ * - dev.* or alt.* → require Basic Auth with ACCESS_PIN env var
+ * - main.* or production domain → no protection, pass through
+ * - No PIN configured → pass through but still set X-Robots-Tag
+ *
+ * The auth check happens BEFORE next() to short-circuit unauthorized access.
+ * X-Robots-Tag is set on ALL dev/alt responses including 401 challenges.
+ *
+ * Uses `cloudflare:workers` env import (Astro v6 removed `context.locals.runtime.env`).
+ * Uses `btoa()` (Workers runtime), not Node.js Buffer.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const accessProtectionMiddleware = defineMiddleware(async (context: any, next: any) => {
+  const host = context.request.headers.get("host") ?? "";
+  const isDevOrAlt = host.startsWith("dev.") || host.startsWith("alt.");
+
+  if (!isDevOrAlt) {
+    return next();
+  }
+
+  const pin = await resolveAccessPin();
+
+  // No PIN set — allow access but still set noindex headers
+  if (!pin) {
+    const response = await next();
+    response.headers.set("X-Robots-Tag", NOINDEX_HEADER);
+    return response;
+  }
+
+  // Check Basic Auth BEFORE calling next()
+  const auth = context.request.headers.get("authorization") ?? "";
+  const expected = `Basic ${btoa(`warp:${pin}`)}`;
+
+  if (auth && constantTimeEqual(auth, expected)) {
+    const response = await next();
+    response.headers.set("X-Robots-Tag", NOINDEX_HEADER);
+    return response;
+  }
+
+  // Not authenticated — challenge with noindex headers
+  return new Response("Authentication required", {
+    status: 401,
+    headers: {
+      "WWW-Authenticate": 'Basic realm="Staging Access"',
+      "X-Robots-Tag": NOINDEX_HEADER,
+    },
+  });
+});