@acms-subir/core 0.3.0 → 0.3.1

package/src/components/ThemeSections.astro

@@ -1,4 +1,5 @@
 ---
+import LiveCard from './LiveCard.astro';
 import type { Page, Settings } from '../lib/schema';
 import { getTheme } from '../lib/theme';
 import { getRepo } from '../lib/repo';
@@ -32,7 +33,7 @@ const sections = await Promise.all(layout.sections.map(async (section) => {
 <div class="acms-sections">
   {sections.filter(s => !s.hidden && !s.invalid).map(({ id, type, variant, data, Template, posts }) => (
     <section id={`section-${id}`} class:list={['acms-section', `section-${type}`, `variant-${variant}`]}>
-      {type === 'page-content' ? (page.bodyHtml ? <article class="page-body" set:html={bodyHtml} /> : <WidgetRenderer pageId={page.id} blocks={page.blocks} />) : Template ? <Template data={data} variant={variant} settings={settings} page={page} /> : (
+      {type === 'live' && !Template ? <LiveCard display={variant} /> : type === 'page-content' ? (page.bodyHtml ? <article class="page-body" set:html={bodyHtml} /> : <WidgetRenderer pageId={page.id} blocks={page.blocks} />) : Template ? <Template data={data} variant={variant} settings={settings} page={page} /> : (
         <>
           <div class="section-copy">
             {data.heading && <h2>{String(data.heading)}</h2>}

package/src/components/WidgetRenderer.astro

@@ -1,4 +1,5 @@
 ---
+import LiveCard from './LiveCard.astro';
 import { parseConfig, type WidgetInstance, type WidgetType } from '../lib/schema';
 import { renderMarkdown } from '../lib/markdown';
 
@@ -21,6 +22,8 @@ const items = blocks.flatMap((b) => {
 
 {items.map(({ block, config }) => {
   switch (block.type) {
+    case 'live':
+      return <LiveCard display={config.display} />;
     case 'hero':
       return (
         <section class={`w-hero ${config.align}`}>

package/src/layouts/Admin.astro

@@ -115,7 +115,6 @@ const groups: { id: string; label: string; items: Item[] }[] = [
               ]
             : []),
           { key: 'calendar:calendars', label: 'Calendars', href: '/admin/calendar/calendars', icon: icons.calendars, count: null },
-          { key: 'calendar:integrations', label: 'API & webhooks', href: '/admin/calendar/integrations', icon: icons.plug, count: null },
         ],
       }]
     : []),
@@ -134,6 +133,7 @@ const groups: { id: string; label: string; items: Item[] }[] = [
     items: [
       { key: 'users', label: 'Users', href: '/admin/users', icon: icons.users, count: null },
       { key: 'ai', label: 'Document import', href: '/admin/ai', icon: icons.posts, count: null },
+      { key: 'integrations', label: 'API & webhooks', href: '/admin/integrations', icon: icons.plug, count: null },
       { key: 'settings', label: 'Settings', href: '/admin/settings', icon: icons.settings, count: null },
     ],
   },

package/src/layouts/Site.astro

@@ -16,6 +16,7 @@ import { analyticsHead, analyticsBody } from '../lib/analytics';
 import { socialIconPath, socialIconSvg } from '../lib/socialIcons';
 import '../styles/site.css';
 import '../styles/cards.css';
+import '../styles/live.css';
 
 interface Props {
   title?: string;
@@ -117,6 +118,9 @@ const htmlLang = reqLocale || siteLang(settings);
 // search modal chrome: strings follow the document language, the form's
 // no-JS fallback goes to the (locale-prefixed) /search page
 const showSearch = !bare && SEARCH.enabled;
+// site-wide live signals: rendered hidden, shown by the shared status poller
+// only while a broadcast is live, so pages keep their normal caching
+const liveSignals = !bare && settings.live.mode !== 'off' ? settings.live.display : null;
 const searchT = searchStrings(htmlLang.slice(0, 2));
 const searchAction = reqLocale && reqLocale !== I18N.defaultLocale ? `/${reqLocale}/search` : '/search';
 // columns footer: brand + tagline + socials, the footer nav, and a "Read"
@@ -204,6 +208,14 @@ const homeJsonLd =
     {settings.headCode && <Fragment set:html={settings.headCode} />}
   </head>
   <body>
+    {liveSignals?.bar && (
+      <div class="pc-live-bar" data-live-bar hidden role="status">
+        <span class="pc-live-mark">Live now</span>
+        <span class="pc-live-bar-title" data-live-bar-title></span>
+        <a data-live-bar-watch href="#">Watch →</a>
+        <button type="button" class="pc-live-x" aria-label="Dismiss live notice">✕</button>
+      </div>
+    )}
     {showAnnouncement && (
       <div class="announcement-bar" data-ann-key={ann.dismissible ? annKey : undefined} hidden={ann.dismissible || undefined}>
         {annLink ? <a href={annLink}>{ann.text}</a> : <span>{ann.text}</span>}
@@ -246,6 +258,7 @@ const homeJsonLd =
             ))}
           </nav>
           <div class="site-tools">
+            {liveSignals?.header && <a class="site-live" data-live-header href="#" hidden>Live</a>}
             {showSearch && (
               <a class="pc-search-trigger" href={searchAction} data-search-open aria-label={searchT.label}>
                 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7" /><path d="m20 20-3.6-3.6" /></svg>
@@ -598,6 +611,21 @@ const homeJsonLd =
         </div>
       </footer>
     )}
+    {liveSignals?.dock && (
+      <div class="pc-live-dock" data-live-dock hidden>
+        <a href="#">
+          <span class="pc-live-dock-thumb"><img alt="" decoding="async" hidden /></span>
+          <span><span class="pc-live-mark">Live</span><b data-live-dock-title></b></span>
+        </a>
+        <button type="button" class="pc-live-x" aria-label="Dismiss live player">✕</button>
+      </div>
+    )}
+    <script>
+      // no-op unless the owner enabled a site-wide live signal above
+      import { mountLiveSignals } from '../lib/live/signals';
+      mountLiveSignals();
+      document.addEventListener('astro:page-load', mountLiveSignals);
+    </script>
     {analyticsBodyHtml && <Fragment set:html={analyticsBodyHtml} />}
     {settings.footerCode && <Fragment set:html={settings.footerCode} />}
   </body>

package/src/lib/api.ts

@@ -18,6 +18,11 @@ export async function readJson(request: Request, maxBytes = 300_000): Promise<un
   return readResponseJson(request, maxBytes);
 }
 export async function readResponseJson(source: Request | Response, maxBytes: number): Promise<unknown> {
+  const bytes = await readResponseBytes(source, maxBytes);
+  try { return JSON.parse(new TextDecoder().decode(bytes)); }
+  catch { throw new ApiError(400, 'Body must be valid JSON.'); }
+}
+export async function readResponseBytes(source: Request | Response, maxBytes: number): Promise<Uint8Array> {
   if (Number(source.headers.get('content-length')) > maxBytes) throw new ApiError(413, 'Payload too large.');
   const reader = source.body?.getReader();
   if (!reader) throw new ApiError(400, 'JSON body is required.');
@@ -35,8 +40,7 @@ export async function readResponseJson(source: Request | Response, maxBytes: num
   const bytes = new Uint8Array(length);
   let offset = 0;
   for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
-  try { return JSON.parse(new TextDecoder().decode(bytes)); }
-  catch { throw new ApiError(400, 'Body must be valid JSON.'); }
+  return bytes;
 }
 export async function requireSession(
   request: Request, cookies: { get(name: string): { value: string } | undefined }, repo: ContentRepository, ownerOnly = false,

package/src/lib/backup/content.ts

@@ -28,7 +28,7 @@ export async function exportContent(repo: ContentRepository, now = Date.now()) {
   ]);
   return {
     format: 'acms-backup' as const, version: 5, exportedAt: new Date(now).toISOString(),
-    settings: { ...settings, ai: { ...settings.ai, enabled: false, encryptedKey: '' }, agent: { ...settings.agent, enabled: false, keyHash: '', keyPrefix: '', allowPublish: false } },
+    settings: { ...settings, live: { ...settings.live, mode: 'off' as const, manual: { watchUrl: '', title: 'We’re live', until: 0 } }, ai: { ...settings.ai, enabled: false, encryptedKey: '' }, agent: { ...settings.agent, enabled: false, keyHash: '', keyPrefix: '', allowPublish: false } },
     pages, posts, media, links, tags, navItems, users, redirects,
     calendars: calendars.map(c => ({ ...c, feedToken: '' })), events,
     resources: resources.map(r => ({ ...r, feedToken: '' })), bookingLinks, ...bookingState,

package/src/lib/live/client.ts

@@ -0,0 +1,88 @@
+import type { PublicLiveSnapshot } from './types';
+
+// One status poller per page, shared by every live surface (cards, the live
+// bar, header marker, dock). Subscribers are tied to an element and dropped
+// once it leaves the DOM (view transitions swap the body).
+//
+// It also mirrors the state onto <html data-live="live|upcoming"> so themes
+// can style anything (an avatar ring, a nav item) without extra markup.
+
+type Listener = (s: PublicLiveSnapshot | null, serverNow: number) => void;
+
+let snapshot: PublicLiveSnapshot | null = null;
+let offset = 0;
+let loaded = false;
+let pending = false;
+let timers: ReturnType<typeof setInterval>[] = [];
+const listeners = new Map<Listener, Element>();
+
+export const serverNow = () => Date.now() + offset;
+
+// a successful observation stops counting as live once it expires, even if
+// every later refresh fails; expiresAt 0 = no expiry (offline fallback)
+function current(): PublicLiveSnapshot | null {
+  if (snapshot && snapshot.expiresAt > 0 && snapshot.expiresAt <= serverNow()) return null;
+  return snapshot;
+}
+
+let shown: PublicLiveSnapshot | null | undefined;
+function emit(force = false) {
+  const s = current();
+  if (!force && s === shown) return;
+  shown = s;
+  const status = s?.status === 'live' || s?.status === 'upcoming' ? s.status : '';
+  if (status) document.documentElement.dataset.live = status;
+  else delete document.documentElement.dataset.live;
+  for (const [fn, el] of listeners) {
+    if (!el.isConnected) { listeners.delete(fn); continue; }
+    fn(s, serverNow());
+  }
+}
+
+async function refresh() {
+  if (pending || document.hidden || !listeners.size) return;
+  pending = true;
+  try {
+    const r = await fetch('/api/live/status', { cache: 'no-store', signal: AbortSignal.timeout(10_000) });
+    if (!r.ok) return;
+    const data = await r.json();
+    if (typeof data.serverNow !== 'number' || !('snapshot' in data)) return;
+    offset = data.serverNow - Date.now();
+    snapshot = data.snapshot;
+    loaded = true;
+    emit(true);
+  } catch {
+    /* keep the last snapshot only until it expires */
+  } finally {
+    pending = false;
+  }
+}
+
+function start() {
+  if (timers.length) return;
+  timers = [
+    setInterval(() => {
+      if (![...listeners.values()].some((el) => el.isConnected)) return;
+      emit();
+    }, 1000),
+    setInterval(refresh, 30_000),
+  ];
+  document.addEventListener('visibilitychange', () => { if (!document.hidden) void refresh(); });
+  window.addEventListener('focus', () => void refresh());
+}
+
+// `initial` is the server-rendered state (live cards embed it); without it the
+// first subscriber triggers a fetch.
+export function subscribeLive(el: Element, fn: Listener, initial?: { snapshot: PublicLiveSnapshot | null; serverNow: number }) {
+  if (initial && !loaded) {
+    offset = initial.serverNow - Date.now();
+    snapshot = initial.snapshot;
+    loaded = true;
+  }
+  listeners.set(fn, el);
+  start();
+  if (loaded) emit(true);
+  else void refresh();
+}
+
+export const currentLive = current;

package/src/lib/live/crypto.ts

@@ -0,0 +1,28 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import { env } from '../env';
+import { ApiError } from '../api';
+function key(locals?: unknown) {
+  const runtime = (locals as { runtime?: { env?: Record<string, unknown> } } | undefined)?.runtime?.env;
+  const secret = String(runtime?.LIVE_ENCRYPTION_KEY || env('LIVE_ENCRYPTION_KEY') || runtime?.SESSION_SECRET || env('SESSION_SECRET'));
+  if (secret.length < 32) throw new ApiError(503, 'Set LIVE_ENCRYPTION_KEY or SESSION_SECRET to at least 32 random characters on your host before storing live credentials.');
+  return createHash('sha256').update(`acms:live:v1:${secret}`).digest();
+}
+export const hash = (value: string) => createHash('sha256').update(value).digest('hex');
+export const randomToken = () => randomBytes(32).toString('base64url');
+export function encryptionReady(locals?: unknown) { try { key(locals); return true; } catch { return false; } }
+export function encrypt(value: unknown, context: string, locals?: unknown) {
+  const iv = randomBytes(12), cipher = createCipheriv('aes-256-gcm', key(locals), iv);
+  cipher.setAAD(Buffer.from(`acms:live:${context}`));
+  const data = Buffer.concat([cipher.update(JSON.stringify(value), 'utf8'), cipher.final()]);
+  return [iv, cipher.getAuthTag(), data].map(v => v.toString('base64url')).join('.');
+}
+export function decrypt<T>(encrypted: string, context: string, locals?: unknown): T {
+  try {
+    const parts = encrypted.split('.');
+    if (parts.length !== 3) throw new Error();
+    const [iv, tag, data] = parts.map(v => Buffer.from(v, 'base64url'));
+    const cipher = createDecipheriv('aes-256-gcm', key(locals), iv);
+    cipher.setAAD(Buffer.from(`acms:live:${context}`)); cipher.setAuthTag(tag);
+    return JSON.parse(Buffer.concat([cipher.update(data), cipher.final()]).toString('utf8'));
+  } catch { throw new ApiError(503, 'Saved live credentials cannot be decrypted. Re-enter the credentials and reconnect.'); }
+}

package/src/lib/live/migration.ts

@@ -0,0 +1,15 @@
+export const LIVE_MIGRATION = { version: 34, statements: [
+  `ALTER TABLE settings ADD COLUMN live TEXT NOT NULL DEFAULT '{}'`,
+  `CREATE TABLE live_connections (
+    provider TEXT PRIMARY KEY CHECK(provider IN ('youtube','twitch')),
+    client_id TEXT NOT NULL, channel_input TEXT NOT NULL DEFAULT '', channel_id TEXT NOT NULL DEFAULT '', channel_name TEXT NOT NULL DEFAULT '',
+    encrypted TEXT NOT NULL, enabled INTEGER NOT NULL DEFAULT 0, revision INTEGER NOT NULL DEFAULT 1,
+    channels TEXT NOT NULL DEFAULT '[]', google_status TEXT NOT NULL DEFAULT 'testing', tested_at INTEGER NOT NULL DEFAULT 0,
+    checked_at INTEGER NOT NULL DEFAULT 0, last_attempt_at INTEGER NOT NULL DEFAULT 0, next_at INTEGER NOT NULL DEFAULT 0,
+    failures INTEGER NOT NULL DEFAULT 0, error TEXT NOT NULL DEFAULT '', lease TEXT NOT NULL DEFAULT '', lease_until INTEGER NOT NULL DEFAULT 0,
+    snapshot TEXT, upcoming TEXT, upcoming_checked_at INTEGER NOT NULL DEFAULT 0
+  )`,
+  `CREATE TABLE live_oauth_states (hash TEXT PRIMARY KEY, session_hash TEXT NOT NULL, revision INTEGER NOT NULL, encrypted TEXT NOT NULL, expires_at INTEGER NOT NULL)`,
+  `CREATE TABLE live_health (id INTEGER PRIMARY KEY CHECK(id=1), last_at INTEGER NOT NULL DEFAULT 0)`,
+  `INSERT INTO live_health (id) VALUES (1)`,
+] };

package/src/lib/live/providers.ts

@@ -0,0 +1,152 @@
+import { z } from 'zod';
+import { readResponseJson } from '../api';
+import { emptySnapshot, type Channel, type Connection, type Credentials, type LiveSnapshot, type Provider } from './types';
+
+export class ProviderError extends Error {
+  constructor(public code: 'auth' | 'quota' | 'unavailable' | 'channel' | 'invalid', message: string, public retryAfter = 0) { super(message); }
+}
+const tokenSchema = z.object({ access_token: z.string().min(1).max(8192), expires_in: z.number().positive(), refresh_token: z.string().max(8192).optional(), scope: z.union([z.string(),z.array(z.string()).transform(v=>v.join(' '))]).optional() });
+const idText = z.string().max(200);
+const ytItem = z.object({ id: idText, snippet: z.object({ channelId: idText.optional(), title: z.string().max(1000), actualStartTime: z.string().optional(), scheduledStartTime: z.string().optional() }), status: z.object({ lifeCycleStatus: z.string().optional(), privacyStatus: z.string().optional() }).optional() });
+const ytPage = z.object({ items: z.array(ytItem).max(50), nextPageToken: z.string().max(1000).optional() });
+const twitchPage = z.object({ data: z.array(z.object({ id: idText, user_id: idText, user_login: idText, user_name: idText.optional(), title: z.string().max(1000), type: z.string(), started_at: z.string(), viewer_count: z.number().int().nonnegative().optional() })).max(100) });
+
+async function request(url: string | URL, init: RequestInit, signal: AbortSignal): Promise<unknown> {
+  try {
+    const r = await fetch(url, { ...init, redirect: 'error', signal: AbortSignal.any([signal, AbortSignal.timeout(10_000)]) });
+    const body = await readResponseJson(r, 512_000).catch(() => null);
+    if (!r.ok) {
+      const detail = z.object({ error: z.union([z.string(), z.object({ errors: z.array(z.object({ reason: z.string() })).optional() })]).optional() }).safeParse(body);
+      const error = detail.success ? detail.data.error : undefined;
+      const quota = r.status === 429 || (typeof error === 'object' && error.errors?.some(e => ['quotaExceeded','dailyLimitExceeded','rateLimitExceeded','userRateLimitExceeded'].includes(e.reason)));
+      if (quota) {
+        const header = r.headers.get('retry-after');
+        const seconds = header && /^\d+$/.test(header) ? Number(header) : header ? (Date.parse(header)-Date.now())/1000 : 0;
+        const reset = Number(r.headers.get('ratelimit-reset') || 0)*1000-Date.now();
+        throw new ProviderError('quota', 'Provider quota or rate limit reached. Check your developer console; automatic checks will retry later.', Math.min(86400_000, Math.max(60_000,Number.isFinite(seconds)?seconds*1000:0,Number.isFinite(reset)?reset:0)));
+      }
+      if (r.status === 401 || r.status === 403 || error === 'invalid_grant' || error === 'invalid_client') throw new ProviderError('auth', 'Access was rejected. Check the saved credentials and authorize again if required.');
+      throw new ProviderError('unavailable', `The provider could not complete the check (HTTP ${r.status}).`);
+    }
+    if (!body) throw new ProviderError('unavailable', 'The provider returned an invalid response.');
+    return body;
+  } catch (e) {
+    if (e instanceof ProviderError) throw e;
+    throw new ProviderError('unavailable', 'The provider did not respond in time. Automatic checks will retry.');
+  }
+}
+const google = (path: string, params: Record<string,string>) => {
+  const url = new URL(`https://www.googleapis.com/youtube/v3/${path}`);
+  Object.entries(params).forEach(([k,v]) => url.searchParams.set(k,v)); return url;
+};
+const bearer = (token: string) => ({ Authorization: `Bearer ${token}` });
+async function validateTwitchToken(clientId: string, creds: Credentials, signal: AbortSignal) {
+  const token = z.object({ client_id: z.string(), expires_in: z.number().nonnegative() }).parse(
+    await request('https://id.twitch.tv/oauth2/validate', { headers: bearer(creds.accessToken!) }, signal),
+  );
+  if (token.client_id !== clientId || token.expires_in <= 60) throw new ProviderError('auth', 'The Twitch token needs renewal.');
+  creds.tokenValidatedAt = Date.now();
+  creds.tokenExpiresAt = Date.now() + token.expires_in * 1000;
+}
+async function getToken(provider: Provider, clientId: string, creds: Credentials, signal: AbortSignal) {
+  if (creds.accessToken && (creds.tokenExpiresAt ?? 0) > Date.now()+60_000) {
+    if (provider !== 'twitch' || (creds.tokenValidatedAt ?? 0) > Date.now()-3600_000) return;
+    try { await validateTwitchToken(clientId, creds, signal); return; }
+    catch (error) {
+      if (!(error instanceof ProviderError) || error.code !== 'auth') throw error;
+      creds.accessToken = ''; creds.tokenExpiresAt = 0;
+    }
+  }
+  const body = new URLSearchParams({ client_id:clientId,client_secret:creds.clientSecret });
+  if (provider === 'twitch') body.set('grant_type','client_credentials');
+  else {
+    if (!creds.refreshToken) throw new ProviderError('auth', 'Authorize YouTube before testing this connection.');
+    body.set('grant_type','refresh_token'); body.set('refresh_token',creds.refreshToken);
+  }
+  // Twitch returns scope as an array on some flows; the client-credentials flow needs neither scope nor refresh token.
+  const data = await request(provider === 'twitch' ? 'https://id.twitch.tv/oauth2/token' : 'https://oauth2.googleapis.com/token', { method:'POST',body },signal);
+  const token = tokenSchema.parse(data);
+  creds.accessToken = token.access_token; creds.tokenExpiresAt = Date.now()+token.expires_in*1000;
+  if (token.refresh_token) creds.refreshToken = token.refresh_token;
+  if (provider === 'twitch') await validateTwitchToken(clientId, creds, signal);
+}
+async function authenticated<T>(conn: Connection, creds: Credentials, signal: AbortSignal, run: () => Promise<T>) {
+  await getToken(conn.provider,conn.clientId,creds,signal);
+  try { return await run(); }
+  catch (e) {
+    if (!(e instanceof ProviderError) || e.code !== 'auth') throw e;
+    creds.accessToken=''; creds.tokenExpiresAt=0;
+    await getToken(conn.provider,conn.clientId,creds,signal);
+    return run(); // One retry, never an unbounded token loop.
+  }
+}
+export function twitchLogin(value: string) {
+  let login = value.trim().toLowerCase();
+  if (/^https?:/i.test(login)) {
+    try { const u=new URL(login); if (u.protocol !== 'https:' || !['twitch.tv','www.twitch.tv'].includes(u.hostname) || u.username || u.password || u.search || u.hash) throw new Error(); login=u.pathname.replace(/^\/|\/$/g,''); }
+    catch { throw new ProviderError('channel','Enter a Twitch channel username or its HTTPS channel URL.'); }
+  }
+  if (!/^[a-z0-9_]{1,25}$/.test(login)) throw new ProviderError('channel','Enter a Twitch channel username or its HTTPS channel URL.');
+  return login;
+}
+export async function channels(conn: Connection, creds: Credentials, signal: AbortSignal): Promise<Channel[]> {
+  return authenticated(conn,creds,signal,async () => {
+    if (conn.provider === 'twitch') {
+      const u=new URL('https://api.twitch.tv/helix/users'); u.searchParams.set('login',twitchLogin(conn.channelInput));
+      const data=z.object({data:z.array(z.object({id:idText,display_name:idText})).max(100)}).parse(await request(u,{headers:{...bearer(creds.accessToken!), 'Client-Id':conn.clientId}},signal));
+      if (!data.data.length) throw new ProviderError('channel','That Twitch channel was not found. Check the username.');
+      return data.data.map(c => ({id:c.id,name:c.display_name}));
+    }
+    const result:Channel[]=[]; let page='';
+    for(let i=0;i<5;i++) {
+      const data=z.object({items:z.array(z.object({id:idText,snippet:z.object({title:idText})})).max(50).default([]),nextPageToken:z.string().optional()}).parse(await request(google('channels',{part:'snippet',mine:'true',maxResults:'50',...(page?{pageToken:page}:{})}),{headers:bearer(creds.accessToken!)},signal));
+      result.push(...data.items.map(c=>({id:c.id,name:c.snippet.title}))); page=data.nextPageToken??''; if (!page) return result;
+    }
+    throw new ProviderError('unavailable','Too many channel results. Connect a Google account with the intended channel identity.');
+  });
+}
+export async function exchangeGoogleCode(clientId:string,clientSecret:string,code:string,verifier:string,callbackUrl:string,signal:AbortSignal):Promise<Credentials> {
+  const token=tokenSchema.parse(await request('https://oauth2.googleapis.com/token',{method:'POST',body:new URLSearchParams({client_id:clientId,client_secret:clientSecret,code,code_verifier:verifier,redirect_uri:callbackUrl,grant_type:'authorization_code'})},signal));
+  if (!token.refresh_token) throw new ProviderError('auth','Google did not provide offline access. Reconnect and approve the read-only permission.');
+  if (!token.scope?.split(' ').includes('https://www.googleapis.com/auth/youtube.readonly')) throw new ProviderError('auth','YouTube read-only permission is required. Reconnect and approve that permission.');
+  return {clientSecret,accessToken:token.access_token,refreshToken:token.refresh_token,tokenExpiresAt:Date.now()+token.expires_in*1000,callbackUrl};
+}
+export async function revoke(provider:Provider,clientId:string,creds:Credentials) {
+  const token=provider==='youtube' ? creds.refreshToken||creds.accessToken : creds.accessToken;
+  if (!token) return;
+  const url=provider==='youtube'?'https://oauth2.googleapis.com/revoke':'https://id.twitch.tv/oauth2/revoke';
+  const body=new URLSearchParams({token,...(provider==='twitch'?{client_id:clientId}:{})});
+  // Revocation is best effort; disconnect always removes local credentials.
+  try { await fetch(url,{method:'POST',body,redirect:'error',signal:AbortSignal.timeout(5_000)}); } catch { /* no provider details in logs */ }
+}
+export async function detect(conn:Connection,creds:Credentials,signal:AbortSignal,upcoming=false):Promise<LiveSnapshot> {
+  return authenticated(conn,creds,signal,async()=>{
+    const now=Date.now();
+    if (!conn.channelId) throw new ProviderError('channel','Choose and test a channel before enabling automatic checks.');
+    if(conn.provider==='twitch') {
+      const u=new URL('https://api.twitch.tv/helix/streams');u.searchParams.set('user_id',conn.channelId);
+      const data=twitchPage.parse(await request(u,{headers:{...bearer(creds.accessToken!), 'Client-Id':conn.clientId}},signal));
+      const stream=data.data.find(s=>s.user_id===conn.channelId&&s.type==='live');
+      if(!stream) return emptySnapshot('twitch',now);
+      const login=twitchLogin(stream.user_login);
+      return {...emptySnapshot('twitch',now),status:'live',id:stream.id,title:stream.title,watchUrl:`https://www.twitch.tv/${login}`,embedId:login,startedAt:Date.parse(stream.started_at)||0,channel:stream.user_name||conn.channelName,viewers:stream.viewer_count};
+    }
+    const found:z.infer<typeof ytItem>[]=[]; let page='';
+    for(let i=0;i<5;i++) {
+      const data=ytPage.parse(await request(google('liveBroadcasts',{part:'snippet,status,contentDetails',broadcastStatus:upcoming?'upcoming':'active',broadcastType:'all',maxResults:'50',...(page?{pageToken:page}:{})}),{headers:bearer(creds.accessToken!)},signal));
+      found.push(...data.items.filter(v=>v.snippet.channelId===conn.channelId && v.status?.privacyStatus==='public' && (upcoming?['created','ready'].includes(v.status?.lifeCycleStatus??''):v.status?.lifeCycleStatus==='live') && /^[\w-]{11}$/.test(v.id)));
+      page=data.nextPageToken??'';if(!page)break;
+      if(i===4)throw new ProviderError('unavailable','Broadcast results exceeded the safe check limit. Narrow the connected channel.');
+    }
+    const start=(v:z.infer<typeof ytItem>)=>Date.parse((upcoming?v.snippet.scheduledStartTime:v.snippet.actualStartTime)??'')||0;
+    found.sort((a,b)=>(upcoming?start(a)-start(b):start(b)-start(a))||a.id.localeCompare(b.id));
+    const item=found[0];if(!item)return emptySnapshot('youtube',now);
+    // Recheck public video visibility and embedding permission before publishing OAuth-derived data.
+    // liveStreamingDetails rides along in the same 1-unit call for the viewer count.
+    const video=z.object({items:z.array(z.object({id:idText,status:z.object({privacyStatus:z.string(),embeddable:z.boolean().optional()}),liveStreamingDetails:z.object({concurrentViewers:z.string().max(20).optional()}).optional()})).default([])}).parse(await request(google('videos',{part:'status,liveStreamingDetails',id:item.id}),{headers:bearer(creds.accessToken!)},signal));
+    const visible=video.items.find(v=>v.id===item.id&&v.status.privacyStatus==='public');
+    if(!visible)return emptySnapshot('youtube',now);
+    const viewers=upcoming?'':visible.liveStreamingDetails?.concurrentViewers?.match(/^\d{1,12}$/)?.[0];
+    return {...emptySnapshot('youtube',now),status:upcoming?'upcoming':'live',id:item.id,title:item.snippet.title,watchUrl:`https://www.youtube.com/watch?v=${item.id}`,embedId:visible.status.embeddable?item.id:'',startedAt:start(item),channel:conn.channelName,...(viewers?{viewers:Number(viewers)}:{})};
+  });
+}

package/src/lib/live/service.ts

@@ -0,0 +1,170 @@
+import { ApiError } from '../api';
+import type { ContentRepository } from '../repo/types';
+import { encrypt, decrypt, encryptionReady, hash, randomToken } from './crypto';
+import { channels, detect, exchangeGoogleCode, ProviderError, revoke, twitchLogin } from './providers';
+import { LiveConfig, type Connection, type Credentials, type Provider, type LiveAdminState, type LiveSnapshot, type PublicLiveSnapshot } from './types';
+
+export function canonicalOrigin(siteUrl: string, requestUrl: URL) {
+  let url: URL;
+  try { url=new URL(siteUrl || requestUrl.origin); } catch { throw new ApiError(400,'Set the site URL before connecting YouTube.'); }
+  if (url.username || url.password || (url.protocol !== 'https:' && !(url.protocol==='http:'&&['localhost','127.0.0.1','[::1]'].includes(url.hostname)))) throw new ApiError(400,'Use an HTTPS site URL (or localhost for development).');
+  return url.origin;
+}
+export function watchSource(raw: string): Pick<LiveSnapshot,'provider'|'id'|'embedId'|'watchUrl'> {
+  const u=new URL(raw);
+  const host=u.hostname.toLowerCase();
+  if(u.protocol!=='https:'||u.username||u.password)throw new ApiError(400,'Use an HTTPS watch URL without credentials.');
+  if(['youtube.com','www.youtube.com','m.youtube.com','youtu.be'].includes(host)) {
+    const id=host==='youtu.be'?u.pathname.slice(1):u.pathname==='/watch'?u.searchParams.get('v'):u.pathname.match(/^\/live\/([^/]+)\/?$/)?.[1];
+    if(id&&/^[\w-]{11}$/.test(id)) return {provider:'youtube',id,embedId:id,watchUrl:`https://www.youtube.com/watch?v=${id}`};
+    return {provider:'youtube',id:'',embedId:'',watchUrl:u.href};
+  }
+  if(['twitch.tv','www.twitch.tv'].includes(host)) { try {const login=twitchLogin(raw);return {provider:'twitch',id:login,embedId:login,watchUrl:`https://www.twitch.tv/${login}`};}catch {return {provider:'twitch',id:'',embedId:'',watchUrl:u.href};} }
+  return {provider:['facebook.com','www.facebook.com','m.facebook.com','fb.watch'].includes(host)?'facebook':'other',id:'',embedId:'',watchUrl:u.href};
+}
+export function effectiveSnapshot(config:LiveConfig,connections:Connection[],now=Date.now()):LiveSnapshot|null {
+  if(config.mode==='off')return null;
+  if(config.mode==='manual'&&config.manual.until>now&&config.manual.watchUrl) {
+    try{return {...watchSource(config.manual.watchUrl),status:'live',source:'manual',title:config.manual.title||'We’re live',startedAt:0,checkedAt:now,expiresAt:config.manual.until};}catch{return null;}
+  }
+  const candidates=config.priority.map(p=>connections.find(c=>c.provider===p&&c.enabled&&c.testedAt>0)).filter((c):c is Connection=>!!c);
+  for(const status of ['live',...(config.showUpcoming?['upcoming']:[])]) {
+    const s=candidates.map(c=>c.snapshot).find(s=>s?.status===status&&s.expiresAt>now);
+    if(s)return s;
+  }
+  if(config.fallbackUrl) {try{return {...watchSource(config.fallbackUrl),embedId:'',status:'offline',source:'automatic',title:'Watch our channel',startedAt:0,checkedAt:now,expiresAt:0};}catch{return null;} }
+  return null;
+}
+// The platform image for a live/upcoming snapshot, derived only from fixed
+// hosts and validated ids, so the thumbnail proxy can never be pointed at an
+// arbitrary URL.
+export function thumbSource(s:LiveSnapshot|null):string {
+  if(!s||(s.status!=='live'&&s.status!=='upcoming'))return '';
+  if(s.provider==='youtube'&&/^[\w-]{11}$/.test(s.id))return `https://i.ytimg.com/vi/${s.id}/${s.status==='live'?'hqdefault_live':'hqdefault'}.jpg`;
+  if(s.provider==='twitch'&&s.status==='live'&&/^[a-z0-9_]{1,25}$/.test(s.embedId))return `https://static-cdn.jtvnw.net/previews-ttv/live_user_${s.embedId}-640x360.jpg`;
+  return '';
+}
+export function publicSnapshot(s:LiveSnapshot|null,config:LiveConfig):PublicLiveSnapshot|null {
+  if(!s)return null;
+  const {viewers,...rest}=s;
+  // The version changes with the broadcast and once a minute, so live
+  // previews refresh while browsers and CDNs can still cache each one.
+  const version=`${s.provider}-${s.id||s.embedId}-${Math.floor(s.checkedAt/60_000)}`.replace(/[^\w-]/g,'');
+  return {...rest,...(config.display.viewers&&typeof viewers==='number'?{viewers}:{}),thumbUrl:config.display.thumbnail&&thumbSource(s)?`/api/live/thumb?v=${version}`:''};
+}
+export async function liveState(repo:ContentRepository) {
+  const [settings,connections]=await Promise.all([repo.getSettings(),repo.live.list()]);
+  return {config:settings.live,snapshot:effectiveSnapshot(settings.live,connections)};
+}
+export async function publicState(repo:ContentRepository) {
+  const {config,snapshot}=await liveState(repo);
+  return publicSnapshot(snapshot,config);
+}
+export async function adminState(repo:ContentRepository,url:URL,locals?:unknown):Promise<LiveAdminState> {
+  const [settings,connections,lastAt]=await Promise.all([repo.getSettings(),repo.live.list(),repo.live.lastHeartbeat()]);
+  let origin=url.origin;try{origin=canonicalOrigin(settings.siteUrl,url);}catch{/* UI can explain the bad site URL when authorizing. */}
+  return {config:settings.live,connections:connections.map(c=>{
+    let authorized=false;try{const s=decrypt<Credentials>(c.encrypted,c.provider,locals);authorized=c.provider==='twitch'?!!s.clientSecret:!!s.refreshToken;}catch{/* needs reconnect */}
+    const {encrypted,lease,leaseUntil,snapshot,upcoming,...visible}=c;
+    return {...visible,hasSecret:!!encrypted,authorized,broadcastStatus:snapshot&&snapshot.expiresAt>Date.now()?snapshot.status:'unknown'};
+  }),callbackUrl:`${origin}/api/live/oauth/youtube/callback`,encryptionReady:encryptionReady(locals),scheduler:{lastAt,healthy:lastAt>Date.now()-180_000},snapshot:effectiveSnapshot(settings.live,connections)};
+}
+const providerError=(error:unknown)=>error instanceof ProviderError?error:error instanceof ApiError?new ProviderError('auth',error.message):new ProviderError('unavailable','The provider returned an unexpected response. Try the connection test again.');
+export async function syncConnection(repo:ContentRepository,provider:Provider,locals?:unknown,force=false):Promise<boolean> {
+  const conn=await repo.live.claim(provider,Date.now(),force);
+  if(!conn) {if(force)throw new ApiError(409,'A check is already running, or was run in the last 10 seconds. Try again shortly.');return false;}
+  let creds:Credentials|undefined;
+  try {
+    creds=decrypt<Credentials>(conn.encrypted,provider,locals);
+    const signal=AbortSignal.timeout(55_000);
+    if(force||!conn.channelId) {
+      conn.channels=await channels(conn,creds,signal);
+      if(!conn.channels.length)throw new ProviderError('channel','No YouTube channel was found. Authorize the Google or Brand account that owns your channel.');
+      const selected=conn.channels.find(c=>c.id===conn.channelId)??(conn.channels.length===1?conn.channels[0]:undefined);
+      if(!selected) {
+        await repo.live.patch(provider,{encrypted:encrypt(creds,provider,locals),channels:conn.channels,testedAt:0,error:'Choose a channel, then test the connection.',nextAt:0},conn.revision,conn.lease);
+        return true;
+      }
+      conn.channelId=selected.id;conn.channelName=selected.name;
+    }
+    let snapshot=await detect(conn,creds,signal);
+    const settings=await repo.getSettings();
+    if(provider==='youtube'&&settings.live.showUpcoming&&snapshot.status==='offline') {
+      if(Date.now()-conn.upcomingCheckedAt>900_000||force) {
+        conn.upcoming=await detect(conn,creds,signal,true);conn.upcomingCheckedAt=Date.now();
+      }
+      if(conn.upcoming?.status==='upcoming'&&conn.upcoming.startedAt>Date.now()) {
+        snapshot={...conn.upcoming,checkedAt:snapshot.checkedAt,expiresAt:Math.min(snapshot.expiresAt,conn.upcomingCheckedAt+900_000,conn.upcoming.startedAt)};
+      }
+    }
+    const ok=await repo.live.patch(provider,{encrypted:encrypt(creds,provider,locals),channels:conn.channels,channelId:conn.channelId,channelName:conn.channelName,snapshot,upcoming:conn.upcoming,upcomingCheckedAt:conn.upcomingCheckedAt,testedAt:Date.now(),checkedAt:snapshot.checkedAt,nextAt:conn.lastAttemptAt+55_000,error:'',failures:0},conn.revision,conn.lease);
+    if(!ok&&force)throw new ApiError(409,'This connection changed during the check. Test the saved connection again.');
+    return ok;
+  }catch(error){
+    if(error instanceof ApiError&&error.status===409)throw error;
+    const failure=providerError(error),attempt=conn.failures+1;
+    const delay=failure.code==='auth'?3600_000:failure.code==='quota'?Math.max(failure.retryAfter,3600_000):Math.min(3600_000,60_000*2**Math.min(attempt,6));
+    // A rotated token must be persisted even if the following lookup fails.
+    let encrypted=conn.encrypted;try{if(creds)encrypted=encrypt(creds,provider,locals);}catch{/* preserve existing ciphertext */}
+    await repo.live.patch(provider,{encrypted,error:failure.message,failures:attempt,nextAt:Date.now()+delay+Math.floor(Math.random()*5000),...(failure.code==='auth'?{snapshot:null,enabled:false,testedAt:0}:{})},conn.revision,conn.lease);
+    if(force)throw new ApiError(400,failure.message);
+    return false;
+  }
+}
+export async function syncDueLive(repo:ContentRepository,locals?:unknown):Promise<number> {
+  await repo.live.heartbeat(Date.now());
+  const connections=(await repo.live.list()).filter(c=>c.enabled&&c.nextAt<=Date.now());
+  const results=await Promise.all(connections.map(c=>syncConnection(repo,c.provider,locals)));
+  return results.filter(Boolean).length;
+}
+export async function saveConnection(repo:ContentRepository,input:{provider:Provider;clientId:string;clientSecret:string;channelInput:string;googleStatus:'testing'|'production'},locals?:unknown) {
+  const current=await repo.live.get(input.provider);
+  if(input.provider==='twitch')twitchLogin(input.channelInput);
+  const same=current?.clientId===input.clientId;
+  let creds:Credentials={clientSecret:input.clientSecret};
+  if(same&&current&&!input.clientSecret)creds=decrypt<Credentials>(current.encrypted,input.provider,locals);
+  if(!creds.clientSecret)throw new ApiError(400,'Enter the client secret for this developer app.');
+  await repo.live.save(input.provider,{...input,encrypted:encrypt(creds,input.provider,locals)});
+  const saved=await repo.live.get(input.provider);
+  if(saved&&(!same||input.provider==='twitch'&&current?.channelInput!==input.channelInput||input.clientSecret))await repo.live.patch(input.provider,{channels:[],channelId:'',channelName:''},saved.revision);
+}
+export async function beginOAuth(repo:ContentRepository,session:string,url:URL,locals?:unknown) {
+  const conn=await repo.live.get('youtube');if(!conn)throw new ApiError(400,'Save your YouTube client ID and secret first.');
+  const creds=decrypt<Credentials>(conn.encrypted,'youtube',locals);
+  if(!creds.clientSecret)throw new ApiError(400,'Save your YouTube client secret first.');
+  const settings=await repo.getSettings(),origin=canonicalOrigin(settings.siteUrl,url);
+  if(origin!==url.origin)throw new ApiError(400,`Open the admin at the configured site origin (${origin}) to authorize YouTube.`);
+  const callbackUrl=`${origin}/api/live/oauth/youtube/callback`,state=randomToken(),verifier=randomToken();
+  await repo.live.state(hash(state),hash(session),conn.revision,encrypt({verifier,callbackUrl},'oauth',locals),Date.now()+600_000);
+  const auth=new URL('https://accounts.google.com/o/oauth2/v2/auth');
+  const params={client_id:conn.clientId,redirect_uri:callbackUrl,response_type:'code',scope:'https://www.googleapis.com/auth/youtube.readonly',access_type:'offline',prompt:'consent select_account',state,code_challenge:Buffer.from(hash(verifier),'hex').toString('base64url'),code_challenge_method:'S256'};
+  Object.entries(params).forEach(([k,v])=>auth.searchParams.set(k,v));return auth.href;
+}
+export async function finishOAuth(repo:ContentRepository,session:string,url:URL,locals?:unknown) {
+  const state=url.searchParams.get('state')??'';
+  if(!/^[\w-]{43}$/.test(state))throw new ApiError(400,'Invalid OAuth state. Start authorization again.');
+  const stored=await repo.live.consumeState(hash(state),hash(session),Date.now());
+  const conn=await repo.live.get('youtube');
+  if(!stored||!conn||stored.revision!==conn.revision)throw new ApiError(400,'Authorization expired or the connection changed. Start again.');
+  if(url.searchParams.has('error'))throw new ApiError(400,'YouTube authorization was not completed. Try again and approve read-only access.');
+  const code=url.searchParams.get('code');if(!code||code.length>8192)throw new ApiError(400,'Missing authorization code.');
+  const {verifier,callbackUrl}=decrypt<{verifier:string;callbackUrl:string}>(stored.encrypted,'oauth',locals);
+  if(new URL(callbackUrl).origin!==url.origin)throw new ApiError(400,'The callback origin does not match the saved site.');
+  const old=decrypt<Credentials>(conn.encrypted,'youtube',locals);
+  try{
+    const creds=await exchangeGoogleCode(conn.clientId,old.clientSecret,code,verifier,callbackUrl,AbortSignal.timeout(30_000));
+    const choices=await channels(conn,creds,AbortSignal.timeout(30_000));
+    if(!choices.length)throw new ProviderError('channel','This Google identity has no YouTube channel. Reconnect with the correct account.');
+    const selected=choices.find(c=>c.id===conn.channelId)??(choices.length===1?choices[0]:undefined);
+    if(!await repo.live.patch('youtube',{encrypted:encrypt(creds,'youtube',locals),channels:choices,channelId:selected?.id??'',channelName:selected?.name??'',enabled:false,testedAt:0,lastAttemptAt:0,error:'',snapshot:null},conn.revision))throw new ApiError(409,'The connection changed. Authorize again.');
+  }catch(e){if(e instanceof ApiError)throw e;throw new ApiError(400,providerError(e).message);}
+}
+export async function disconnect(repo:ContentRepository,provider:Provider,locals?:unknown) {
+  const conn=await repo.live.get(provider);await repo.live.remove(provider);
+  if(conn){try{await revoke(provider,conn.clientId,decrypt<Credentials>(conn.encrypted,provider,locals));}catch{/* local removal succeeds even when old key cannot be read */}}
+}
+export function validateConfig(raw:unknown) {
+  const config=LiveConfig.parse(raw);
+  if(config.mode==='manual'&&(!config.manual.watchUrl||config.manual.until<=Date.now()||config.manual.until>Date.now()+12*3600_000+60_000))throw new ApiError(400,'Manual live status needs a watch URL and an expiry within the next 12 hours.');
+  return config;
+}