Janady13/thatstupidcomputer / packages/site/truth.ts

1import { createHash } from 'node:crypto'; 2import { readFileSync } from 'node:fs'; 3import { isIP } from 'node:net'; 4import { SITE_NAME, SITE_ORIGIN, SITE_SOCIAL_IMAGE } from './content.ts'; 5 6export type Deployment = 'preview' | 'production'; 7export type CanonicalEntityType = 'Person' | 'Organization' | 'Brand'; 8export interface PublicCrawlerPolicy { 9 /** Backward-compatible default; explicit provider choices take precedence. */ 10 training: 'allow' | 'deny'; 11 openaiTraining?: 'allow' | 'deny'; 12 anthropicTraining?: 'allow' | 'deny'; 13 mistralTraining?: 'allow' | 'deny'; 14 googleExtended: 'allow' | 'deny'; 15 source: 'preview-default' | 'deployment-config'; 16} 17export interface PublicEntity { 18 id: string; 19 type: CanonicalEntityType; 20 name: string; 21 url: string; 22 email?: string; 23 telephone?: string; 24} 25export interface PublicSiteConfig { 26 deployment: Deployment; 27 canonicalOrigin: string; 28 siteName: string; 29 websiteId: string; 30 contact: { email?: string; phone?: string }; 31 crawlerPolicy: PublicCrawlerPolicy; 32 /** References to the canonical graph; never local Person/Organization declarations. */ 33 brand?: PublicEntity; 34 publisher?: PublicEntity; 35 provider?: PublicEntity; 36 approvedOrganization?: PublicEntity; 37 ga4MeasurementId?: string; 38 verification?: { google?: string; bing?: string }; 39 socialImage?: { url: string; alt: string; width: number; height: number }; 40 truthStatus: 'unavailable-preview' | 'approved-projection'; 41} 42export interface TruthProjection { 43 schemaVersion: 'tsc-public-projection/v1'; 44 audience: 'public'; 45 provenance: { sourceCommit: string; exportedAt: string }; 46 approval: { 47 status: 'approved-for-publication'; 48 reviewedAt: string; 49 expiresAt: string; 50 /** Opaque canonical claim IDs only. Private evidence remains in the canonical repository. */ 51 claimRefs: string[]; 52 /** Explicit JSON pointers for every leaf under site and entities. */ 53 approvedPaths: string[]; 54 }; 55 site: { 56 origin: string; 57 name: string; 58 websiteId: string; 59 publisherId: string; 60 providerId: string; 61 brandId?: string; 62 contactId?: string; 63 socialImage?: { url: string; alt: string; width: number; height: number }; 64 }; 65 entities: PublicEntity[]; 66} 67type UnknownRecord = Record<string, unknown>; 68function object(value: unknown, path: string): UnknownRecord { 69 if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${path}: expected object`); 70 return value as UnknownRecord; 71} 72function keys(value: UnknownRecord, allowed: string[], required: string[], path: string): void { 73 for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`${path}: field is not in the public allowlist`); 74 for (const key of required) if (!(key in value)) throw new Error(`${path}.${key}: required`); 75} 76function plain(value: unknown, path: string, max = 240): string { 77 if (typeof value !== 'string' || !value.trim() || value.length > max || /[<>\u0000-\u001f\u007f]/.test(value)) throw new Error(`${path}: invalid public string`); 78 return value; 79} 80/** Public HTTPS references only: no credentials, query tokens, local hosts or literal IPs. */ 81export function publicUrl(value: unknown, path = 'url'): string { 82 const input = plain(value, path, 1200); 83 let url: URL; 84 try { url = new URL(input); } catch { throw new Error(`${path}: invalid URL`); } 85 const host = url.hostname.toLowerCase(); 86 if (url.protocol !== 'https:' || url.username || url.password || url.search || (url.port && url.port !== '443') || 87 !host.includes('.') || host.endsWith('.') || isIP(host.replace(/^\[|\]$/g, '')) || 88 /(^|\.)(localhost|local|internal|test|invalid|example|lan|home|onion)$/.test(host) || 89 /^(example\.(com|net|org))$/.test(host) || /(?:\.ts\.net|\.localhost)$/.test(host) || 90 /(?:^|\/)(?:private|secrets?|credentials?|admin|\.git|\.env)(?:\/|$)/i.test(decodeURIComponent(url.pathname))) { 91 throw new Error(`${path}: URL is not eligible for public projection`); 92 } 93 return input; // Exact canonical identifier bytes are preserved; never normalized or re-minted. 94} 95function timestamp(value: unknown, path: string): number { 96 const text = plain(value, path, 40); 97 if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(text) || !Number.isFinite(Date.parse(text))) throw new Error(`${path}: UTC timestamp required`); 98 return Date.parse(text); 99} 100function leaves(value: unknown, prefix: string): string[] { 101 if (value && typeof value === 'object') return Object.entries(value).flatMap(([key, entry]) => leaves(entry, `${prefix}/${key}`)); 102 return [prefix]; 103} 104/** Structural policy check. Actual claim truth/permission is reviewed upstream, never inferred here. */ 105export function validateProjection(input: unknown, options: { now?: Date; expectedCommit?: string } = {}): TruthProjection { 106 const raw = object(input, 'projection'); 107 keys(raw, ['schemaVersion', 'audience', 'provenance', 'approval', 'site', 'entities'], ['schemaVersion', 'audience', 'provenance', 'approval', 'site', 'entities'], 'projection'); 108 if (raw.schemaVersion !== 'tsc-public-projection/v1' || raw.audience !== 'public') throw new Error('An explicitly public tsc-public-projection/v1 export is required'); 109 const provenance = object(raw.provenance, 'provenance'); 110 keys(provenance, ['sourceCommit', 'exportedAt'], ['sourceCommit', 'exportedAt'], 'provenance'); 111 if (typeof provenance.sourceCommit !== 'string' || !/^[a-f0-9]{40,64}$/.test(provenance.sourceCommit) || ![40, 64].includes(provenance.sourceCommit.length)) throw new Error('provenance.sourceCommit: full Git commit required'); 112 if (options.expectedCommit && provenance.sourceCommit !== options.expectedCommit) throw new Error('Projection source commit does not match the pinned canonical revision'); 113 const now = (options.now ?? new Date()).getTime(); 114 const exported = timestamp(provenance.exportedAt, 'provenance.exportedAt'); 115 const approval = object(raw.approval, 'approval'); 116 keys(approval, ['status', 'reviewedAt', 'expiresAt', 'claimRefs', 'approvedPaths'], ['status', 'reviewedAt', 'expiresAt', 'claimRefs', 'approvedPaths'], 'approval'); 117 if (approval.status !== 'approved-for-publication') throw new Error('Projection is not approved for publication'); 118 const reviewed = timestamp(approval.reviewedAt, 'approval.reviewedAt'); 119 const expires = timestamp(approval.expiresAt, 'approval.expiresAt'); 120 if (reviewed > now || exported > now || exported < reviewed || expires <= now || expires <= reviewed) throw new Error('Projection review/export timing is stale or inconsistent'); 121 if (!Array.isArray(approval.claimRefs) || approval.claimRefs.length === 0 || approval.claimRefs.length > 200 || approval.claimRefs.some((ref) => typeof ref !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9:._/#-]{0,199}$/.test(ref))) throw new Error('approval.claimRefs: canonical claim references required'); 122 const site = object(raw.site, 'site'); 123 keys(site, ['origin', 'name', 'websiteId', 'publisherId', 'providerId', 'brandId', 'contactId', 'socialImage'], ['origin', 'name', 'websiteId', 'publisherId', 'providerId'], 'site'); 124 if (site.origin !== SITE_ORIGIN || site.name !== SITE_NAME) throw new Error('Projection does not target the approved TSC website'); 125 for (const key of ['websiteId', 'publisherId', 'providerId', 'brandId', 'contactId']) if (site[key] !== undefined) publicUrl(site[key], `site.${key}`); 126 if (new URL(site.websiteId as string).origin !== SITE_ORIGIN) throw new Error('WebSite ID must belong to the site-owned canonical origin'); 127 if (site.socialImage !== undefined) { 128 const img = object(site.socialImage, 'site.socialImage'); 129 keys(img, ['url', 'alt', 'width', 'height'], ['url', 'alt', 'width', 'height'], 'site.socialImage'); 130 publicUrl(img.url, 'site.socialImage.url'); plain(img.alt, 'site.socialImage.alt', 500); 131 if (new URL(img.url as string).origin !== SITE_ORIGIN) throw new Error('Social image must use the approved website origin'); 132 for (const key of ['width', 'height']) if (!Number.isInteger(img[key]) || Number(img[key]) < 1 || Number(img[key]) > 10000) throw new Error(`site.socialImage.${key}: invalid dimension`); 133 } 134 if (!Array.isArray(raw.entities) || raw.entities.length < 1 || raw.entities.length > 8) throw new Error('entities: bounded canonical public projection required'); 135 const ids = new Map<string, PublicEntity>(); 136 raw.entities.forEach((entry, index) => { 137 const entity = object(entry, `entities/${index}`); 138 keys(entity, ['id', 'type', 'name', 'url', 'email', 'telephone'], ['id', 'type', 'name', 'url'], `entities/${index}`); 139 const id = publicUrl(entity.id, `entities/${index}/id`); 140 publicUrl(entity.url, `entities/${index}/url`); 141 plain(entity.name, `entities/${index}/name`); 142 if (!['Person', 'Organization', 'Brand'].includes(String(entity.type))) throw new Error('Only approved canonical Person/Organization/Brand references are accepted'); 143 if (ids.has(id) || id === site.websiteId) throw new Error('Canonical entity IDs must be unique and distinct from the WebSite'); 144 if (entity.email !== undefined && (typeof entity.email !== 'string' || entity.email.length > 254 || !/^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/.test(entity.email))) throw new Error('Invalid approved public email'); 145 if (entity.telephone !== undefined && (typeof entity.telephone !== 'string' || !/^\+[1-9]\d{6,14}$/.test(entity.telephone))) throw new Error('Public telephone must use E.164 format'); 146 if (entity.type === 'Brand' && (entity.email !== undefined || entity.telephone !== undefined)) throw new Error('Contact belongs to the actual Person/Organization, not an inferred Brand operator'); 147 ids.set(id, entity as unknown as PublicEntity); 148 }); 149 for (const key of ['publisherId', 'providerId']) { 150 const entity = ids.get(site[key] as string); 151 if (!entity || !['Organization', 'Person'].includes(entity.type)) throw new Error(`site.${key}: must reference an approved Person or Organization, never Brand or WebSite`); 152 } 153 if (site.brandId !== undefined && ids.get(site.brandId as string)?.type !== 'Brand') throw new Error('site.brandId: must reference an approved Brand'); 154 if (site.contactId !== undefined && !['publisherId', 'providerId'].some((key) => site[key] === site.contactId)) throw new Error('Contact must reference the approved publisher or provider'); 155 const used = new Set([site.publisherId, site.providerId, site.brandId, site.contactId].filter(Boolean)); 156 if ([...ids.keys()].some((id) => !used.has(id))) throw new Error('Unreferenced entities are not allowed in the public projection'); 157 const requiredPaths = [...leaves(raw.site, '/site'), ...leaves(raw.entities, '/entities')].sort(); 158 const approvedPaths = approval.approvedPaths; 159 if (!Array.isArray(approvedPaths) || approvedPaths.some((path) => typeof path !== 'string') || new Set(approvedPaths).size !== approvedPaths.length || JSON.stringify([...approvedPaths].sort()) !== JSON.stringify(requiredPaths)) throw new Error('Every projected public field must have an exact approval path; extra approval paths are rejected'); 160 return structuredClone(raw) as unknown as TruthProjection; 161} 162export function resolveCrawlerPolicy(deployment: Deployment, training?: string, googleExtended?: string, overrides: { openai?: string; anthropic?: string; mistral?: string } = {}): PublicCrawlerPolicy { 163 for (const [name, value] of [['AI_TRAINING_POLICY', training], ['GOOGLE_EXTENDED_POLICY', googleExtended], ['OPENAI_TRAINING_POLICY', overrides.openai], ['ANTHROPIC_TRAINING_POLICY', overrides.anthropic], ['MISTRAL_TRAINING_POLICY', overrides.mistral]]) { 164 if (value !== undefined && value !== 'allow' && value !== 'deny') throw new Error(`${name} must explicitly be allow or deny`); 165 } 166 if (deployment === 'production' && (!training || !googleExtended)) throw new Error('Production blocked: explicitly configure AI_TRAINING_POLICY and GOOGLE_EXTENDED_POLICY from the actual owner-approved crawler policy'); 167 return { 168 training: (training ?? 'deny') as 'allow' | 'deny', 169 openaiTraining: (overrides.openai ?? training ?? 'deny') as 'allow' | 'deny', 170 anthropicTraining: (overrides.anthropic ?? training ?? 'deny') as 'allow' | 'deny', 171 mistralTraining: (overrides.mistral ?? training ?? 'deny') as 'allow' | 'deny', 172 googleExtended: (googleExtended ?? 'deny') as 'allow' | 'deny', 173 source: training && googleExtended ? 'deployment-config' : 'preview-default', 174 }; 175} 176export function configFromProjection(projection: TruthProjection, deployment: Deployment, crawlerPolicy?: PublicCrawlerPolicy): PublicSiteConfig { 177 const policy = crawlerPolicy ?? resolveCrawlerPolicy(deployment); 178 if (deployment === 'production' && policy.source !== 'deployment-config') throw new Error('Production requires an explicit crawler policy'); 179 const find = (id: string | undefined) => projection.entities.find((entity) => entity.id === id); 180 const publisher = find(projection.site.publisherId)!; 181 const provider = find(projection.site.providerId)!; 182 const contact = find(projection.site.contactId); 183 return { 184 deployment, canonicalOrigin: SITE_ORIGIN, siteName: SITE_NAME, websiteId: projection.site.websiteId, crawlerPolicy: policy, 185 publisher, provider, ...(find(projection.site.brandId) ? { brand: find(projection.site.brandId) } : {}), 186 ...(publisher.type === 'Organization' ? { approvedOrganization: publisher } : {}), 187 contact: { ...(contact?.email ? { email: contact.email } : {}), ...(contact?.telephone ? { phone: contact.telephone } : {}) }, 188 socialImage: projection.site.socialImage ?? { ...SITE_SOCIAL_IMAGE }, truthStatus: 'approved-projection', 189 }; 190} 191export interface LoadSiteConfigOptions { 192 deployment: Deployment; 193 projectionPath?: string; 194 ga4MeasurementId?: string; 195 googleSiteVerification?: string; 196 bingSiteVerification?: string; 197 aiTrainingPolicy?: string; 198 openaiTrainingPolicy?: string; 199 anthropicTrainingPolicy?: string; 200 mistralTrainingPolicy?: string; 201 googleExtendedPolicy?: string; 202 expectedCommit?: string; 203 expectedSha256?: string; 204} 205export function loadSiteConfig(options: LoadSiteConfigOptions): PublicSiteConfig { 206 const optional = (value: string | undefined): string | undefined => value === '' ? undefined : value; 207 if (!['preview', 'production'].includes(options.deployment)) throw new Error('Explicit preview or production deployment mode required'); 208 const projectionPath = options.projectionPath ?? process.env.TSC_TRUTH_PROJECTION; 209 const expectedCommit = options.expectedCommit ?? process.env.TSC_TRUTH_COMMIT; 210 const expectedSha256 = options.expectedSha256 ?? process.env.TSC_TRUTH_SHA256; 211 if (options.deployment === 'production' && (!projectionPath || !expectedCommit || !expectedSha256)) throw new Error('Production blocked: supply canonical public projection, TSC_TRUTH_COMMIT and TSC_TRUTH_SHA256 pins'); 212 const crawlerPolicy = resolveCrawlerPolicy(options.deployment, optional(options.aiTrainingPolicy ?? process.env.AI_TRAINING_POLICY), optional(options.googleExtendedPolicy ?? process.env.GOOGLE_EXTENDED_POLICY), { 213 openai: optional(options.openaiTrainingPolicy ?? process.env.OPENAI_TRAINING_POLICY), 214 anthropic: optional(options.anthropicTrainingPolicy ?? process.env.ANTHROPIC_TRAINING_POLICY), 215 mistral: optional(options.mistralTrainingPolicy ?? process.env.MISTRAL_TRAINING_POLICY), 216 }); 217 let config: PublicSiteConfig = { 218 deployment: options.deployment, canonicalOrigin: SITE_ORIGIN, siteName: SITE_NAME, 219 websiteId: `${SITE_ORIGIN}/#website`, contact: {}, crawlerPolicy, socialImage: { ...SITE_SOCIAL_IMAGE }, truthStatus: 'unavailable-preview', 220 }; 221 if (projectionPath) { 222 const bytes = readFileSync(projectionPath); 223 if (bytes.length > 64_000) throw new Error('Public projection exceeds bounded adapter size'); 224 const digest = createHash('sha256').update(bytes).digest('hex'); 225 if (expectedSha256 && (!/^[a-f0-9]{64}$/.test(expectedSha256) || digest !== expectedSha256)) throw new Error('Public projection digest does not match the pinned reviewed export'); 226 config = configFromProjection(validateProjection(JSON.parse(bytes.toString('utf8')), { expectedCommit }), options.deployment, crawlerPolicy); 227 } 228 const ga4MeasurementId = optional(options.ga4MeasurementId); 229 if (ga4MeasurementId !== undefined) { 230 if (!/^G-[A-Z0-9]{5,20}$/.test(ga4MeasurementId)) throw new Error('Invalid public GA4 measurement ID'); 231 config.ga4MeasurementId = ga4MeasurementId; 232 } 233 const google = optional(options.googleSiteVerification ?? process.env.GOOGLE_SITE_VERIFICATION); 234 const bing = optional(options.bingSiteVerification ?? process.env.BING_SITE_VERIFICATION); 235 for (const [provider, token] of [['Google', google], ['Bing', bing]]) { 236 if (token !== undefined && !/^[A-Za-z0-9_-]{10,256}$/.test(token)) throw new Error(`${provider} site verification requires a safe bounded token, not pasted HTML or a secret`); 237 } 238 if (google || bing) config.verification = { ...(google ? { google } : {}), ...(bing ? { bing } : {}) }; 239 return config; 240} 241