@supersuit/artifacts 0.58.2 → 0.59.0

package/template/hub/app/frapp/route.ts

@@ -0,0 +1,28 @@
+// GET /frapp: the door every texted tile app link opens first, on the operator's own hub and in its
+// own brand pack. See src/lib/frapp-door.mjs.
+//
+// The tailnet target rides in the URL FRAGMENT, which the browser never sends, so this handler
+// cannot see, log or store a key even by accident. It reads only `?k=` (a kind from a closed
+// list) and `?t=` (the page title), so the share card can say what is being sent.
+import { doorHtml } from '@/lib/frapp-door.mjs'
+import { DOOR_CSP, doorTheme } from '@/lib/frapp-door-theme'
+import { hubTenant } from '@/tenant'
+
+export const dynamic = 'force-dynamic'
+
+export function GET(req: Request) {
+  const tenant = hubTenant()
+  const url = new URL(req.url)
+  const html = doorHtml({ origin: tenant.siteUrl, kind: url.searchParams.get('k'), title: url.searchParams.get('t'), theme: doorTheme(tenant) })
+  return new Response(html, {
+    status: 200,
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+      'content-security-policy': DOOR_CSP,
+      'referrer-policy': 'no-referrer',
+      'x-content-type-options': 'nosniff',
+      'x-robots-tag': 'noindex, nofollow',
+      'cache-control': 'public, max-age=300',
+    },
+  })
+}

package/template/hub/app/globals.css

@@ -0,0 +1,7 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+body {
+  font-family: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif;
+}

package/template/hub/app/layout.tsx

@@ -0,0 +1,32 @@
+import type { Metadata } from 'next'
+import { parseHubEnv } from '@/lib/hub-env-parse'
+import { hubMetadata } from '@/lib/hub-meta'
+// The default pack's faces (DM Serif Display over DM Sans), self-hosted.
+import '@fontsource/dm-serif-display/400.css'
+import '@fontsource/dm-sans/400.css'
+import '@fontsource/dm-sans/500.css'
+import '@fontsource/dm-sans/600.css'
+import './globals.css'
+
+// A hub may carry its own look, with its own web fonts.
+const hub = parseHubEnv(process.env.HUB_TENANT)
+const hubPack = hub?.pack
+
+export function generateMetadata(): Metadata {
+  return hubMetadata(hub)
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      {hubPack?.fontsUrl && (
+        <head>
+          <link rel="preconnect" href="https://fonts.googleapis.com" />
+          <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+          <link rel="stylesheet" href={hubPack.fontsUrl} />
+        </head>
+      )}
+      <body className="antialiased">{children}</body>
+    </html>
+  )
+}

package/template/hub/app/page.tsx

@@ -0,0 +1,26 @@
+// The hub's home. Pages are shared by link, so there is nothing to list here; this says whose
+// pages these are and stops.
+import { BrandGround, BrandMark } from '@supersuit/artifacts/brand'
+import { hubTenant } from '@/tenant'
+
+export const dynamic = 'force-dynamic'
+
+export default function Home() {
+  const t = hubTenant()
+  return (
+    <BrandGround pack={t.pack}>
+      <div className="mx-auto max-w-2xl px-6 pt-32 text-center">
+        <BrandMark pack={t.pack} className="mx-auto mb-6 block h-14 w-auto text-5xl" />
+        <p className="text-[11px] uppercase tracking-[0.3em]" style={{ color: t.pack.accent }}>
+          {t.pack.kicker}
+        </p>
+        <h1 className="mt-4 text-3xl" style={{ fontFamily: t.pack.type.display }}>
+          {t.configured ? `Pages ${t.owner ?? t.pack.name} shares by link` : 'This hub is not configured yet'}
+        </h1>
+        <p className="mt-4 opacity-70">
+          {t.configured ? 'If you were sent one, the link takes you straight to it.' : 'Its setup sets HUB_TENANT when it deploys it.'}
+        </p>
+      </div>
+    </BrandGround>
+  )
+}

package/template/hub/app/robots.ts

@@ -0,0 +1,6 @@
+import type { MetadataRoute } from 'next'
+
+// Every page here is shared by link and none is meant to be found.
+export default function robots(): MetadataRoute.Robots {
+  return { rules: { userAgent: '*', disallow: '/' } }
+}

package/template/hub/apphosting.yaml

@@ -0,0 +1,21 @@
+# The shape of a hub's settings. Every "__SET_BY_SETUP__" value is replaced at deploy time by the
+# apphosting.hub.yaml override that create-or-update-my-artifact-hub writes; the secrets are created
+# in the hub's own Secret Manager by the same setup.
+runConfig:
+  minInstances: 0
+  maxInstances: 2
+env:
+  - variable: HUB_TENANT
+    value: "__SET_BY_SETUP__"
+  - variable: FIREBASE_STORAGE_BUCKET
+    value: "__SET_BY_SETUP__"
+  - variable: ARTIFACT_PRIVATE_BUCKET
+    value: "__SET_BY_SETUP__"
+  - variable: TENANT_PUBLISH_KEY_HUB
+    secret: hub-publish-key
+  - variable: ARTIFACT_PASS_SECRET
+    secret: artifact-pass-secret
+  # Signs per-reader links (`links: per-reader`, and every shared review). Without it the hub
+  # answers 501 "this host keeps no per-reader links".
+  - variable: ARTIFACT_RECIPIENT_SECRET
+    secret: artifact-recipient-secret

package/template/hub/firestore.indexes.json

@@ -0,0 +1,13 @@
+{
+  "indexes": [
+    {
+      "collectionGroup": "artifactState",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "slot", "order": "ASCENDING" },
+        { "fieldPath": "at", "order": "ASCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}

package/template/hub/next.config.ts

@@ -0,0 +1,27 @@
+import type { NextConfig } from 'next'
+// Relative and import-free on purpose: Next's config loader does not resolve the `@/` alias.
+import { parseHubEnv } from './src/lib/hub-env-parse'
+
+const nextConfig: NextConfig = {
+  poweredByHeader: false,
+  images: { formats: ['image/avif', 'image/webp'] },
+  // Loaded at runtime from node_modules rather than bundled, like firebase-admin.
+  serverExternalPackages: ['@google-cloud/storage'],
+  // Firebase's Google sign-in handler, served same-origin so Safari keeps the sign-in. No host
+  // condition: behind App Hosting the request's Host header is not the public host, so a
+  // `has: host` match would never fire and Google sign-in would 404.
+  async rewrites() {
+    const hub = parseHubEnv(process.env.HUB_TENANT)
+    return hub ? [{ source: '/__/auth/:path*', destination: `https://${hub.firebase.projectId}.firebaseapp.com/__/auth/:path*` }] : []
+  },
+  // The share card and the door's card read the package's font from disk at request time. Next's
+  // tracer does not follow the package's own literal into node_modules, so these are load-bearing.
+  // The key is a glob: '[id]' would be a character class and match nothing.
+  outputFileTracingIncludes: {
+    '/*/share.png': ['./node_modules/@supersuit/artifacts/fonts/**'],
+    '/frapp/og': ['./node_modules/@supersuit/artifacts/fonts/**'],
+    '/frapp/font': ['./node_modules/@supersuit/artifacts/fonts/**'],
+  },
+}
+
+export default nextConfig

package/template/hub/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "supersuit-artifact-hub",
+  "version": "0.0.0",
+  "private": true,
+  "description": "One operator's own artifact hub: the @supersuit/artifacts shell as a deployable Next.js app for Firebase App Hosting, configured entirely by HUB_TENANT.",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@fontsource/dm-sans": "^5.3.0",
+    "@fontsource/dm-serif-display": "^5.3.0",
+    "@google-cloud/storage": "^7.22.0",
+    "@supersuit/artifacts": "0.59.0",
+    "firebase": "^12.19.0",
+    "firebase-admin": "^13.7.0",
+    "next": "^16.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "autoprefixer": "^10",
+    "postcss": "^8",
+    "tailwindcss": "^3.4.1",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/template/hub/postcss.config.mjs

@@ -0,0 +1,2 @@
+const config = { plugins: { tailwindcss: {}, autoprefixer: {} } }
+export default config

package/template/hub/proxy.ts

@@ -0,0 +1,24 @@
+// Ahead of a page: a per-reader link that was revoked, or whose broadcast passed its date, answers
+// 410 Gone with the same quiet words the page shows, so preview services and crawlers drop it.
+//
+// Only a request carrying a reader's link (`?r=`) or its cookie (`artifact_r_<id>`) can be shut, so
+// that cheap check runs first and loads nothing. A store that fails to answer never costs a reader
+// the page: the page itself refuses a shut link.
+import { NextResponse, type NextRequest } from 'next/server'
+
+const RID_COOKIE = 'artifact_r_'
+
+export async function proxy(request: NextRequest) {
+  const carriesLink = request.nextUrl.searchParams.has('r') || request.cookies.getAll().some((c) => c.name.startsWith(RID_COOKIE))
+  if (!carriesLink) return NextResponse.next()
+  try {
+    const { hubRoutes } = await import('@/lib/routes')
+    const shut = await hubRoutes().shutPageResponse(request)
+    if (shut) return shut
+  } catch {
+    // Fall through to the page, which applies the same gate.
+  }
+  return NextResponse.next()
+}
+
+export const config = { matcher: ['/:id([a-z0-9]{8})'] }

package/template/hub/src/lib/brand-colors.ts

@@ -0,0 +1,13 @@
+// What the hub's pages actually render in, reduced to three colours, for /brand.json. Supersuit's
+// publish script compares this with the brand universe the operator's workspace loads, so a pack
+// that has fallen behind is named on the next publish instead of being noticed by eye. The pack's opening mode decides which
+// palette counts: a light-mode pack renders its `light` palette, every other its dark one.
+import type { BrandPack } from '@supersuit/artifacts/brand'
+
+export type BrandColors = { ground: string; text: string; accent: string; mode: string; pack: string }
+
+export function brandColors(pack: BrandPack): BrandColors {
+  const mode = pack.mode ?? 'dark'
+  const p = mode === 'light' && pack.light ? pack.light : { ground: pack.ground, ink: pack.ink, accent: pack.accent }
+  return { ground: p.ground, text: p.ink, accent: p.accent, mode, pack: pack.id }
+}

package/template/hub/src/lib/firebase-admin.ts

@@ -0,0 +1,46 @@
+// Firestore, Storage and Auth for the hub, through Application Default Credentials: on App Hosting
+// that is the backend's own runtime service account, so no key is stored anywhere. For a local run,
+// FIREBASE_SERVICE_ACCOUNT_KEY (one line of service account JSON) is used instead when it is set.
+import { initializeApp, getApps, cert, applicationDefault, type ServiceAccount } from 'firebase-admin/app'
+import { getFirestore, type Firestore } from 'firebase-admin/firestore'
+import { getStorage } from 'firebase-admin/storage'
+import { getAuth, type Auth } from 'firebase-admin/auth'
+import type { Bucket } from '@google-cloud/storage'
+
+let _db: Firestore | null = null
+let _bucket: Bucket | null = null
+let _privateBucket: Bucket | null = null
+
+function getAdminApp() {
+  if (getApps().length > 0) return getApps()[0]
+  const key = process.env.FIREBASE_SERVICE_ACCOUNT_KEY?.trim()
+  const credential = key ? cert(JSON.parse(key) as ServiceAccount) : applicationDefault()
+  const storageBucket = process.env.FIREBASE_STORAGE_BUCKET?.trim() || undefined
+  return initializeApp({ credential, ...(storageBucket ? { storageBucket } : {}) })
+}
+
+export function getAdminDb(): Firestore {
+  return (_db ??= getFirestore(getAdminApp()))
+}
+
+/** The project's default bucket (FIREBASE_STORAGE_BUCKET): public page media. */
+export function getAdminBucket(): Bucket {
+  return (_bucket ??= getStorage(getAdminApp()).bucket() as unknown as Bucket)
+}
+
+/**
+ * The bucket private media (`media: private`) lives in, named by ARTIFACT_PRIVATE_BUCKET. It must
+ * not be the public bucket: that one carries a bucket-wide public read grant. Unset or blank means
+ * no private store, and the package then refuses private media instead of making it public.
+ */
+export function getAdminPrivateBucket(): Bucket | undefined {
+  const name = process.env.ARTIFACT_PRIVATE_BUCKET?.trim()
+  if (!name || name === '__SET_BY_SETUP__') return undefined
+  if (_privateBucket?.name !== name) _privateBucket = getStorage(getAdminApp()).bucket(name) as unknown as Bucket
+  return _privateBucket
+}
+
+/** ID-token verification for readers signing in on this host (src/lib/local-sign-in.ts). */
+export function getAdminAuth(): Auth {
+  return getAuth(getAdminApp())
+}

package/template/hub/src/lib/frapp-door-theme.ts

@@ -0,0 +1,56 @@
+// The door wears the hub it is served on (src/lib/frapp-door.mjs). The door is plain HTML under a
+// strict CSP, so a pack's React parts (Wrapper, Mark) cannot run there; this reduces a pack to what
+// plain HTML can wear: its palettes, its kicker and its display face (served by /frapp/font from
+// the pack's own share-card font).
+import { createHash } from 'node:crypto'
+import type { BrandPack } from '@supersuit/artifacts/brand'
+import { DOOR_SCRIPT, type DoorTheme } from './frapp-door.mjs'
+import type { Tenant } from '@/tenant'
+
+/** A CSS font stack with its `var(--…)` entries dropped: the door loads no next/font variables. */
+export function plainStack(stack: string): string {
+  const parts = stack.split(',').map((s) => s.trim()).filter((s) => s && !s.startsWith('var('))
+  return parts.length ? parts.join(', ') : 'Georgia, serif'
+}
+
+export function doorTheme(tenant: Tenant, pack: BrandPack = tenant.pack): DoorTheme {
+  return {
+    name: pack.name,
+    kicker: pack.kicker,
+    scheme: pack.mode ?? 'dark',
+    dark: { ground: pack.ground, ink: pack.ink, accent: pack.accent },
+    light: pack.light ?? null,
+    display: plainStack(pack.type.display),
+    font: Boolean(pack.share?.font),
+    mark: null,
+    backdrop: null,
+  }
+}
+
+const SCRIPT_HASH = createHash('sha256').update(DOOR_SCRIPT).digest('base64')
+
+/** The door's CSP. Nothing loads but its own inline script (by hash) and style, its own mark,
+ *  backdrop and face, and the one probe the page makes, which may only go to a tailnet host. */
+export const DOOR_CSP = [
+  "default-src 'none'",
+  `script-src 'sha256-${SCRIPT_HASH}'`,
+  "style-src 'unsafe-inline'",
+  "img-src 'self'",
+  "font-src 'self'",
+  'connect-src https://*.ts.net',
+  "base-uri 'none'",
+  "form-action 'none'",
+  "frame-ancestors 'none'",
+].join('; ')
+
+// renderShareCard caches a pack's font and backdrop by pack object, so one derived pack per
+// tenant and kicker keeps that cache warm.
+const cardPacks = new Map<string, BrandPack>()
+
+/** The tenant's pack with the door card's kicker on it, for the shell's share card. */
+export function cardPack(tenantId: string, pack: BrandPack, kicker: string): BrandPack {
+  const key = `${tenantId}\u0000${kicker}`
+  let p = cardPacks.get(key)
+  if (!p) cardPacks.set(key, (p = { ...pack, kicker }))
+  return p
+}

package/template/hub/src/lib/frapp-door.d.mts

@@ -0,0 +1,24 @@
+export type DoorPalette = { ground: string; ink: string; accent: string };
+export type DoorTheme = {
+  name: string;
+  kicker: string;
+  scheme: 'dark' | 'light' | 'system';
+  dark: DoorPalette;
+  light: DoorPalette | null;
+  display: string;
+  /** The tenant's display face is served at /frapp/font. */
+  font: boolean;
+  mark: { src: string; width: number; height: number } | null;
+  backdrop: string | null;
+};
+export function doorTarget(raw: unknown): string | null;
+export function doorFragment(hash: unknown): string | null;
+export function lnaGated(): Promise<boolean>;
+export const DOOR_SCRIPT: string;
+export const DOOR_KINDS: Record<string, { title: string; line: string }>;
+export const TITLE_MAX: number;
+export function doorTitle(t: unknown): string | null;
+export function doorCard(k: unknown, t?: unknown): { kind: string | null; kindTitle: string; line: string; title: string | null; heading: string };
+export function doorHtml(opts?: { origin?: string; kind?: string | null; title?: string | null; theme?: Partial<DoorTheme> }): string;
+/** The frapp door version this deploy serves, reported on /api/health (supersuit-dev#1182). */
+export const DOOR_VERSION: number;