Open History to see the last commit
1/**
2 * Integrity verification — the online counterpart to `verify()`'s offline
3 * file check: re-fetch every manifest entry at its pinned
4 * `?version=<contentHash>` address, recompute the hash locally, and fail
5 * on any mismatch. The hash mirrors the server's content addressing
6 * (SHA-256 of the recursively key-sorted JSON), so a match proves the
7 * service serves exactly the bytes the pinned hash names — nothing to
8 * take on trust. Full re-derivation from the upstream provider spec lives
9 * in the service repo (`bun scripts/rederive.ts <provider>`); the
10 * `provenance` echoed per check says which upstream document to audit.
11 */
12import { createHash } from 'node:crypto'
13
14import { readManifest } from './manifest.ts'
15import { DEFAULT_BASE_URL } from './pull.ts'
16import type { PullConfig } from './pull.ts'
17import { LABEL_KIND } from './selection.ts'
18import type { Kind, KindLabel } from './selection.ts'
19
20function sortValue(value: unknown): unknown {
21 if (Array.isArray(value)) return value.map(sortValue)
22 if (value !== null && typeof value === 'object') {
23 const sorted: Record<string, unknown> = {}
24 for (const key of Object.keys(value).sort()) {
25 sorted[key] = sortValue((value as Record<string, unknown>)[key])
26 }
27 return sorted
28 }
29 return value
30}
31
32/** SHA-256 of the stable-stringified value — must equal the server's
33 * `contentHash` (src/server/kv.ts) for the same schema. */
34export function schemaContentHash(value: unknown): string {
35 return createHash('sha256')
36 .update(JSON.stringify(sortValue(value)))
37 .digest('hex')
38}
39
40/** The `provenance` object served with every JSON schema read. */
41export interface SchemaProvenance {
42 sourceUrl: string | null
43 sourceHash: string | null
44 fetchedAt: number
45 extractorVersion: string | null
46}
47
48export interface IntegrityCheck {
49 key: string
50 contentHash: string
51 ok: boolean
52 problem?: string
53 provenance?: SchemaProvenance | null
54}
55
56export interface IntegrityResult {
57 ok: boolean
58 checks: Array<IntegrityCheck>
59 /** Failures not tied to one manifest entry (e.g. missing manifest). */
60 problems: Array<string>
61}
62
63interface ParsedKey {
64 provider: string
65 activity: string
66 endpointId: string
67 kind: Kind
68}
69
70/** Manifest keys are `provider/activity/endpointId#request|response`. */
71function parseKey(key: string): ParsedKey | null {
72 const hashIndex = key.lastIndexOf('#')
73 if (hashIndex === -1) return null
74 const kind = LABEL_KIND[key.slice(hashIndex + 1) as KindLabel] as
75 | Kind
76 | undefined
77 if (kind === undefined) return null
78 const [provider, activity, ...endpoint] = key.slice(0, hashIndex).split('/')
79 if (provider === undefined || activity === undefined || endpoint.length === 0)
80 return null
81 return { provider, activity, endpointId: endpoint.join('/'), kind }
82}
83
84export async function verifyIntegrity(
85 config: PullConfig,
86): Promise<IntegrityResult> {
87 const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '')
88 const fetchImpl = config.fetchImpl ?? fetch
89 const log = config.log ?? (() => undefined)
90 const manifest = await readManifest(config.outDir)
91 if (manifest === null) {
92 return {
93 ok: false,
94 checks: [],
95 problems: [
96 `No ${config.outDir}/.manifest.json — run \`modelschemas pull\` first.`,
97 ],
98 }
99 }
100
101 const checks: Array<IntegrityCheck> = []
102 for (const [key, entry] of Object.entries(manifest.entries)) {
103 const target = parseKey(key)
104 if (target === null) {
105 checks.push({
106 key,
107 contentHash: entry.contentHash,
108 ok: false,
109 problem: `Unparseable manifest key — regenerate with \`modelschemas pull\`.`,
110 })
111 continue
112 }
113 const path =
114 `/v1/schemas/${encodeURIComponent(target.provider)}/${encodeURIComponent(target.activity)}/` +
115 target.endpointId.split('/').map(encodeURIComponent).join('/') +
116 `?kind=${target.kind}&version=${encodeURIComponent(entry.contentHash)}`
117
118 let check: IntegrityCheck
119 try {
120 const response = await fetchImpl(`${baseUrl}${path}`, {
121 headers:
122 config.apiKey !== undefined
123 ? { Authorization: `Bearer ${config.apiKey}` }
124 : {},
125 })
126 if (response.status === 404) {
127 check = {
128 key,
129 contentHash: entry.contentHash,
130 ok: false,
131 problem: `Service no longer serves the pinned version ${entry.contentHash}.`,
132 }
133 } else if (!response.ok) {
134 check = {
135 key,
136 contentHash: entry.contentHash,
137 ok: false,
138 problem: `GET ${path} → ${String(response.status)}`,
139 }
140 } else {
141 const body = (await response.json()) as {
142 contentHash: string
143 schema: unknown
144 provenance?: SchemaProvenance | null
145 }
146 const recomputed = schemaContentHash(body.schema)
147 const ok =
148 recomputed === entry.contentHash &&
149 body.contentHash === entry.contentHash
150 check = {
151 key,
152 contentHash: entry.contentHash,
153 ok,
154 ...(ok
155 ? {}
156 : {
157 problem: `Content hash mismatch: manifest ${entry.contentHash}, served ${body.contentHash}, recomputed ${recomputed}.`,
158 }),
159 provenance: body.provenance ?? null,
160 }
161 }
162 } catch (error) {
163 check = {
164 key,
165 contentHash: entry.contentHash,
166 ok: false,
167 problem: error instanceof Error ? error.message : String(error),
168 }
169 }
170 checks.push(check)
171 log(`${check.ok ? 'verified' : 'FAILED'} ${key}`)
172 }
173 return { ok: checks.every((c) => c.ok), checks, problems: [] }
174}