@acms-subir/core 0.2.0 → 0.3.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;
+}

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