@acms-subir/core 0.3.0 → 0.3.2

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;
+}

package/src/lib/live/signals.ts

@@ -0,0 +1,89 @@
+import { subscribeLive } from './client';
+import type { PublicLiveSnapshot } from './types';
+
+// Site-wide live signals (Site.astro renders them hidden when the owner
+// enables them): the live bar, the header marker and the floating dock. All
+// three appear only while a broadcast is actually live, and dismissals last
+// for that broadcast in this browser session.
+
+const dismissKey = (what: string, s: PublicLiveSnapshot) => `acms-live-${what}-${s.provider}-${s.id || s.watchUrl}`;
+const dismissed = (what: string, s: PublicLiveSnapshot) => {
+  try { return sessionStorage.getItem(dismissKey(what, s)) === '1'; } catch { return false; }
+};
+const dismiss = (what: string, s: PublicLiveSnapshot) => {
+  try { sessionStorage.setItem(dismissKey(what, s), '1'); } catch { /* private mode: dismiss for this page only */ }
+};
+
+// a live card already on the page makes the dock redundant and gives the
+// header marker a local target
+function pageCard(): HTMLElement | null {
+  const card = Array.from(document.querySelectorAll<HTMLElement>('[data-live-card]')).find((c) => !c.hidden && c.dataset.status === 'live');
+  if (card && !card.id) card.id = 'live-video';
+  return card ?? null;
+}
+
+function openExternally(a: HTMLAnchorElement, url: string) {
+  a.href = url;
+  a.target = '_blank';
+  a.rel = 'noopener noreferrer';
+}
+
+export function mountLiveSignals() {
+  const bar = document.querySelector<HTMLElement>('[data-live-bar]:not([data-ready])');
+  const marker = document.querySelector<HTMLAnchorElement>('[data-live-header]:not([data-ready])');
+  const dock = document.querySelector<HTMLElement>('[data-live-dock]:not([data-ready])');
+  let current: PublicLiveSnapshot | null = null;
+
+  if (bar) {
+    bar.dataset.ready = '';
+    bar.querySelector('.pc-live-x')?.addEventListener('click', () => {
+      if (current) dismiss('bar', current);
+      bar.hidden = true;
+      delete document.documentElement.dataset.liveBar;
+    });
+    subscribeLive(bar, (s) => {
+      current = s;
+      const show = s?.status === 'live' && !dismissed('bar', s);
+      bar.hidden = !show;
+      if (show) document.documentElement.dataset.liveBar = '';
+      else delete document.documentElement.dataset.liveBar;
+      if (!s || !show) return;
+      bar.querySelector('[data-live-bar-title]')!.textContent = s.title;
+      const card = pageCard();
+      const a = bar.querySelector<HTMLAnchorElement>('[data-live-bar-watch]')!;
+      if (card) { a.href = `#${card.id}`; a.removeAttribute('target'); } else openExternally(a, s.watchUrl);
+    });
+  }
+
+  if (marker) {
+    marker.dataset.ready = '';
+    subscribeLive(marker, (s) => {
+      marker.hidden = s?.status !== 'live';
+      if (!s || marker.hidden) return;
+      const card = pageCard();
+      marker.title = s.title;
+      if (card) { marker.href = `#${card.id}`; marker.removeAttribute('target'); } else openExternally(marker, s.watchUrl);
+    });
+  }
+
+  if (dock) {
+    dock.dataset.ready = '';
+    const link = dock.querySelector<HTMLAnchorElement>('a')!;
+    const img = dock.querySelector<HTMLImageElement>('img')!;
+    img.addEventListener('load', () => { img.hidden = false; });
+    img.addEventListener('error', () => { img.hidden = true; });
+    dock.querySelector('.pc-live-x')?.addEventListener('click', () => {
+      if (current) dismiss('dock', current);
+      dock.hidden = true;
+    });
+    subscribeLive(dock, (s) => {
+      current = s;
+      dock.hidden = s?.status !== 'live' || dismissed('dock', s) || !!pageCard();
+      if (!s || dock.hidden) return;
+      openExternally(link, s.watchUrl);
+      dock.querySelector('[data-live-dock-title]')!.textContent = s.title;
+      if (!s.thumbUrl) { img.hidden = true; img.removeAttribute('src'); }
+      else if (img.getAttribute('src') !== s.thumbUrl) img.src = s.thumbUrl;
+    });
+  }
+}

package/src/lib/live/store.ts

@@ -0,0 +1,49 @@
+import { randomInt } from 'node:crypto';
+import type { SqlDriver } from '../repo/sql';
+import type { Connection, Provider, LiveSnapshot, Channel } from './types';
+const parse = <T>(raw: unknown, fallback: T): T => { try { return raw ? JSON.parse(String(raw)) : fallback; } catch { return fallback; } };
+function connection(r: Record<string, unknown>): Connection {
+  return { provider: r.provider as Provider, clientId: String(r.client_id), channelInput: String(r.channel_input), channelId: String(r.channel_id), channelName: String(r.channel_name), encrypted: String(r.encrypted), enabled: !!r.enabled, revision: Number(r.revision), channels: parse<Channel[]>(r.channels, []), googleStatus: r.google_status as Connection['googleStatus'], testedAt: Number(r.tested_at), checkedAt: Number(r.checked_at), lastAttemptAt: Number(r.last_attempt_at), nextAt: Number(r.next_at), failures: Number(r.failures), error: String(r.error), lease: String(r.lease), leaseUntil: Number(r.lease_until), snapshot: parse<LiveSnapshot | null>(r.snapshot, null), upcoming: parse<LiveSnapshot | null>(r.upcoming, null), upcomingCheckedAt: Number(r.upcoming_checked_at) };
+}
+const columns: Record<string, string> = { clientId:'client_id', channelInput:'channel_input', channelId:'channel_id', channelName:'channel_name', encrypted:'encrypted', enabled:'enabled', channels:'channels', googleStatus:'google_status', testedAt:'tested_at', checkedAt:'checked_at', lastAttemptAt:'last_attempt_at', nextAt:'next_at', failures:'failures', error:'error', snapshot:'snapshot', upcoming:'upcoming', upcomingCheckedAt:'upcoming_checked_at' };
+const serialized = new Set(['channels','snapshot','upcoming']);
+export class LiveStore {
+  constructor(private driver: () => Promise<SqlDriver>) {}
+  async list() { return (await (await this.driver()).all('SELECT * FROM live_connections ORDER BY provider')).map(connection); }
+  async get(provider: Provider) { return (await this.list()).find(c => c.provider === provider) ?? null; }
+  // Revisions invalidate in-flight provider requests and OAuth callbacks when a setting changes.
+  async save(provider: Provider, data: { clientId: string; channelInput: string; encrypted: string; googleStatus: string }) {
+    // A recreated connection must not reuse the revision of an in-flight OAuth callback.
+    const revision = randomInt(1, 2 ** 48 - 1);
+    await (await this.driver()).run(`INSERT INTO live_connections (provider,client_id,channel_input,encrypted,google_status,revision) VALUES (?,?,?,?,?,?)
+      ON CONFLICT(provider) DO UPDATE SET client_id=excluded.client_id,channel_input=excluded.channel_input,encrypted=excluded.encrypted,google_status=excluded.google_status,
+      enabled=0,tested_at=0,revision=revision+1,lease='',lease_until=0,snapshot=NULL,upcoming=NULL,upcoming_checked_at=0,error='',failures=0,next_at=0`, [provider,data.clientId,data.channelInput,data.encrypted,data.googleStatus,revision]);
+  }
+  async patch(provider: Provider, data: Partial<Connection>, revision: number, lease?: string): Promise<boolean> {
+    const entries = Object.entries(data).filter(([k]) => columns[k]);
+    if (!entries.length) return false;
+    const args = entries.map(([k,v]) => serialized.has(k) ? v == null ? null : JSON.stringify(v) : typeof v === 'boolean' ? Number(v) : v);
+    const rows = await (await this.driver()).all(`UPDATE live_connections SET ${entries.map(([k]) => `${columns[k]}=?`).join(',')},
+      ${lease ? "lease='',lease_until=0" : "revision=revision+1,lease='',lease_until=0"}
+      WHERE provider=? AND revision=?${lease ? ' AND lease=?' : ''} RETURNING provider`, [...args,provider,revision,...(lease ? [lease] : [])]);
+    return rows.length > 0;
+  }
+  async claim(provider: Provider, now: number, force = false) {
+    const lease = crypto.randomUUID();
+    const rows = await (await this.driver()).all(`UPDATE live_connections SET lease=?,lease_until=?,last_attempt_at=?
+      WHERE provider=? AND lease_until<=? AND ${force ? '(last_attempt_at=0 OR last_attempt_at<=?)' : 'enabled=1 AND next_at<=?'} RETURNING *`, [lease,now+90_000,now,provider,now,force ? now-10_000 : now]);
+    return rows[0] ? connection(rows[0]) : null;
+  }
+  async remove(provider: Provider) {
+    await (await this.driver()).batch([{sql:'DELETE FROM live_connections WHERE provider=?',args:[provider]}, ...(provider === 'youtube' ? [{sql:'DELETE FROM live_oauth_states'}] : [])]);
+  }
+  async state(hash: string, sessionHash: string, revision: number, encrypted: string, expiresAt: number) {
+    await (await this.driver()).batch([{sql:'DELETE FROM live_oauth_states WHERE expires_at<? OR session_hash=?',args:[Date.now(),sessionHash]}, {sql:'INSERT INTO live_oauth_states (hash,session_hash,revision,encrypted,expires_at) VALUES (?,?,?,?,?)',args:[hash,sessionHash,revision,encrypted,expiresAt]}]);
+  }
+  async consumeState(hash: string, sessionHash: string, now: number) {
+    const rows = await (await this.driver()).all('DELETE FROM live_oauth_states WHERE hash=? AND session_hash=? AND expires_at>? RETURNING revision,encrypted', [hash,sessionHash,now]);
+    return rows[0] ? {revision:Number(rows[0].revision),encrypted:String(rows[0].encrypted)} : null;
+  }
+  async heartbeat(now: number) { await (await this.driver()).run('UPDATE live_health SET last_at=? WHERE id=1',[now]); }
+  async lastHeartbeat() { return Number((await (await this.driver()).all('SELECT last_at FROM live_health WHERE id=1'))[0]?.last_at ?? 0); }
+}

package/src/lib/live/types.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+export const Provider = z.enum(['youtube', 'twitch']);
+export type Provider = z.infer<typeof Provider>;
+const httpsUrl = z.string().trim().max(2048).refine(v => { if (!v) return true; try { const u = new URL(v); return u.protocol === 'https:' && !u.username && !u.password; } catch { return false; } }, 'Use an HTTPS URL without credentials.');
+export const LiveConfig = z.object({
+  mode: z.enum(['off', 'automatic', 'manual']).default('off'),
+  priority: z.array(Provider).max(2).default(['youtube', 'twitch']).refine(v => new Set(v).size === v.length, 'Choose each provider only once.'),
+  fallbackUrl: httpsUrl.default(''),
+  showUpcoming: z.boolean().default(false),
+  manual: z.object({ watchUrl: httpsUrl.default(''), title: z.string().trim().max(200).default('We’re live'), until: z.number().int().nonnegative().default(0) }).strict().default({}),
+  // How the public site presents the snapshot. Site-wide signals start off so
+  // an upgrade never changes an existing site without the owner opting in.
+  display: z.object({
+    style: z.enum(['poster', 'split', 'row']).default('poster'),
+    thumbnail: z.boolean().default(true),
+    viewers: z.boolean().default(false),
+    bar: z.boolean().default(false),
+    header: z.boolean().default(false),
+    dock: z.boolean().default(false),
+  }).strict().default({}),
+}).strict();
+export type LiveConfig = z.infer<typeof LiveConfig>;
+export interface LiveSnapshot {
+  status: 'live' | 'offline' | 'upcoming' | 'unknown';
+  source: 'automatic' | 'manual';
+  provider: Provider | 'facebook' | 'other';
+  id: string; title: string; watchUrl: string; embedId: string;
+  startedAt: number; checkedAt: number; expiresAt: number;
+  // optional: snapshots stored before these existed parse unchanged
+  channel?: string; viewers?: number;
+}
+// What visitors receive: viewers only when the owner opts in, and a same-site
+// thumbnail URL (empty when disabled or the provider has no image).
+export interface PublicLiveSnapshot extends Omit<LiveSnapshot, 'viewers'> { viewers?: number; thumbUrl: string }
+export interface Channel { id: string; name: string }
+export interface Credentials { clientSecret: string; accessToken?: string; refreshToken?: string; tokenExpiresAt?: number; tokenValidatedAt?: number; callbackUrl?: string }
+export interface Connection {
+  provider: Provider; clientId: string; channelInput: string; channelId: string; channelName: string;
+  encrypted: string; enabled: boolean; revision: number; channels: Channel[];
+  googleStatus: 'testing' | 'production'; testedAt: number; checkedAt: number; lastAttemptAt: number;
+  nextAt: number; failures: number; error: string; lease: string; leaseUntil: number;
+  snapshot: LiveSnapshot | null; upcoming: LiveSnapshot | null; upcomingCheckedAt: number;
+}
+export interface PublicConnection extends Omit<Connection, 'encrypted' | 'lease' | 'leaseUntil' | 'snapshot' | 'upcoming'> {
+  hasSecret: boolean; authorized: boolean; broadcastStatus: LiveSnapshot['status'];
+}
+export interface LiveAdminState {
+  config: LiveConfig; connections: PublicConnection[]; callbackUrl: string;
+  encryptionReady: boolean; scheduler: { lastAt: number; healthy: boolean };
+  snapshot: LiveSnapshot | null;
+}
+export const emptySnapshot = (provider: Provider, now: number): LiveSnapshot => ({ status: 'offline', source: 'automatic', provider, id: '', title: '', watchUrl: '', embedId: '', startedAt: 0, checkedAt: now, expiresAt: now + 120_000 });

package/src/lib/live/view.ts

@@ -0,0 +1,78 @@
+import type { PublicLiveSnapshot } from './types';
+
+// Display text for a live snapshot. Pure and DOM-free: LiveCard renders it on
+// the server and the browser re-applies it on every status change, so both
+// always agree.
+
+export const PROVIDER_NAMES: Record<string, string> = { youtube: 'YouTube', twitch: 'Twitch', facebook: 'Facebook', other: '' };
+
+export interface LiveView {
+  status: 'live' | 'upcoming' | 'offline';
+  provider: string;
+  // poster tag: "LIVE" or "Sat 7:00 PM · in 2 h"
+  tag: string;
+  // marker line above the title: "LIVE ON TWITCH"
+  kicker: string;
+  title: string;
+  // "heymunmusic · started 42 min ago"
+  meta: string;
+  viewers: string;
+  watchLabel: string;
+  watchUrl: string;
+  thumbUrl: string;
+}
+
+const MIN = 60_000, HOUR = 60 * MIN, DAY = 24 * HOUR;
+
+export function compactCount(n: number): string {
+  if (n < 1000) return String(n);
+  const [v, unit] = n < 1e6 ? [n / 1e3, 'K'] : [n / 1e6, 'M'];
+  return `${v < 10 ? Math.floor(v * 10) / 10 : Math.floor(v)}${unit}`;
+}
+
+export function ago(ms: number): string {
+  if (ms < MIN) return 'just now';
+  if (ms < HOUR) return `${Math.floor(ms / MIN)} min ago`;
+  const h = Math.floor(ms / HOUR), m = Math.floor((ms % HOUR) / MIN);
+  return m ? `${h} h ${m} min ago` : `${h} h ago`;
+}
+
+export function until(ms: number): string {
+  if (ms < MIN) return 'starting now';
+  if (ms < HOUR) return `in ${Math.ceil(ms / MIN)} min`;
+  if (ms < DAY) return `in ${Math.round(ms / HOUR)} h`;
+  const d = Math.round(ms / DAY);
+  return `in ${d} day${d === 1 ? '' : 's'}`;
+}
+
+export function when(ts: number, now: number): string {
+  const d = new Date(ts);
+  const time = d.toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' });
+  if (ts - now < 6 * DAY) return `${d.toLocaleDateString(undefined, { weekday: 'short' })} ${time}`;
+  return `${d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })} ${time}`;
+}
+
+export function liveView(s: PublicLiveSnapshot | null, now: number): LiveView | null {
+  if (!s || (s.status !== 'live' && s.status !== 'upcoming' && s.status !== 'offline')) return null;
+  const name = PROVIDER_NAMES[s.provider] ?? '';
+  const channel = s.channel?.trim() ?? '';
+  const base = { status: s.status, provider: s.provider, title: s.title, watchUrl: s.watchUrl, thumbUrl: s.thumbUrl };
+  if (s.status === 'offline') {
+    return { ...base, tag: '', kicker: '', meta: channel, viewers: '', thumbUrl: '', watchLabel: 'Watch our channel ↗' };
+  }
+  const watchLabel = name ? `Watch on ${name} ↗` : 'Watch now ↗';
+  if (s.status === 'upcoming') {
+    const start = s.startedAt > 0 ? `${when(s.startedAt, now)} · ${until(s.startedAt - now)}` : '';
+    return {
+      ...base, tag: start || 'UPCOMING', kicker: name ? `UPCOMING ON ${name.toUpperCase()}` : 'UPCOMING',
+      meta: [channel, name && 'scheduled'].filter(Boolean).join(' · '), viewers: '', watchLabel: name ? `Open on ${name} ↗` : 'Open ↗',
+    };
+  }
+  const started = s.startedAt > 0 && s.startedAt <= now ? `started ${ago(now - s.startedAt)}` : '';
+  return {
+    ...base, tag: 'LIVE', kicker: name ? `LIVE ON ${name.toUpperCase()}` : 'LIVE NOW',
+    meta: [channel, started].filter(Boolean).join(' · '),
+    viewers: typeof s.viewers === 'number' ? `${compactCount(s.viewers)} watching` : '',
+    watchLabel,
+  };
+}

package/src/lib/repo/index.ts

@@ -1,23 +1,27 @@
 import type { ContentRepository } from './types';
 
-let repo: ContentRepository | null = null;
+// The promise (not the instance) is cached: concurrent first requests would
+// otherwise each create a repository and race to run pending migrations.
+let repo: Promise<ContentRepository> | null = null;
 
 // Adapter priority: Cloudflare D1 (when the Worker binding exists —
 // production on Workers and local wrangler/astro dev via platformProxy)
 // → libSQL file (plain Node self-hosting).
 // Pass Astro.locals (or the endpoint's `locals`) so the D1 binding is
 // reachable; the chosen adapter is cached for the isolate's lifetime.
-export async function getRepo(locals?: unknown): Promise<ContentRepository> {
-  if (repo) return repo;
+export function getRepo(locals?: unknown): Promise<ContentRepository> {
+  repo ??= create(locals).catch((e) => { repo = null; throw e; });
+  return repo;
+}
+
+async function create(locals?: unknown): Promise<ContentRepository> {
   const d1 = (locals as { runtime?: { env?: { DB?: unknown } } } | undefined)?.runtime?.env?.DB;
   if (d1) {
     const { D1Repository } = await import('./d1');
-    repo = new D1Repository(d1 as import('./d1').D1Database);
-  } else {
-    const { SqliteRepository } = await import('./sqlite');
-    repo = new SqliteRepository();
+    return new D1Repository(d1 as import('./d1').D1Database);
   }
-  return repo;
+  const { SqliteRepository } = await import('./sqlite');
+  return new SqliteRepository();
 }
 
 export type { ContentRepository };

package/src/lib/repo/migrations.ts

@@ -1,4 +1,6 @@
+import { LIVE_MIGRATION } from '../live/migration';
 import { EMAIL_MIGRATION } from '../email/migration';
+import { WEBHOOK_MIGRATION } from '../webhook-sql';
 // Versioned schema migrations shared by the two SQLite-dialect adapters
 // (D1 and libSQL). Applied versions are recorded in the `migrations` table;
 // each adapter's runner applies whatever is newer, in order, at startup.
@@ -495,6 +497,8 @@ export const MIGRATIONS: Migration[] = [
       actual_revision INTEGER NOT NULL CHECK (expected_revision = actual_revision)
     )`,
   ] },
+  WEBHOOK_MIGRATION,
+  LIVE_MIGRATION,
 ];
 
 export const LATEST_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;