Skip to content

Commit 2e820ce

Browse files
committed
feat: add OCI resolver for skillet artifacts
1 parent 721eca5 commit 2e820ce

2 files changed

Lines changed: 520 additions & 0 deletions

File tree

‎src/resolvers/oci.ts‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
import crypto from "node:crypto";
2+
import fs from "node:fs";
3+
import os from "node:os";
4+
import path from "node:path";
5+
import { execFileSync } from "node:child_process";
6+
7+
export class OciResolveError extends Error {}
8+
9+
export type ParsedOciReference = {
10+
registry: string;
11+
repository: string;
12+
referenceType: "tag" | "digest";
13+
reference: string;
14+
};
15+
16+
export type ResolveOciSourceOptions = {
17+
tempRoot?: string;
18+
insecureHttp?: boolean;
19+
};
20+
21+
export type ResolvedOciSource = {
22+
parsed: ParsedOciReference;
23+
resolvedDigest: string;
24+
extractPath: string;
25+
contentPath: string;
26+
};
27+
28+
const SKILLET_ARTIFACT_TYPE = "application/vnd.skillet.skill.v1+tar";
29+
30+
export function parseOciReference(source: string): ParsedOciReference {
31+
const trimmed = source.trim();
32+
if (!trimmed.startsWith("oci://")) {
33+
throw new OciResolveError("OCI reference must start with oci://");
34+
}
35+
36+
const withoutScheme = trimmed.slice("oci://".length);
37+
const slashIndex = withoutScheme.indexOf("/");
38+
if (slashIndex <= 0) {
39+
throw new OciResolveError(`Invalid OCI reference: ${source}`);
40+
}
41+
42+
const registry = withoutScheme.slice(0, slashIndex);
43+
const remainder = withoutScheme.slice(slashIndex + 1);
44+
45+
if (!registry || !remainder) {
46+
throw new OciResolveError(`Invalid OCI reference: ${source}`);
47+
}
48+
49+
if (remainder.includes("@")) {
50+
const [repository, digest] = remainder.split("@", 2);
51+
if (!repository || !digest) {
52+
throw new OciResolveError(`Invalid OCI digest reference: ${source}`);
53+
}
54+
55+
return {
56+
registry,
57+
repository,
58+
referenceType: "digest",
59+
reference: digest,
60+
};
61+
}
62+
63+
const tagIndex = remainder.lastIndexOf(":");
64+
if (tagIndex <= 0 || tagIndex === remainder.length - 1) {
65+
throw new OciResolveError(`OCI tag reference must include :tag or @digest: ${source}`);
66+
}
67+
68+
return {
69+
registry,
70+
repository: remainder.slice(0, tagIndex),
71+
referenceType: "tag",
72+
reference: remainder.slice(tagIndex + 1),
73+
};
74+
}
75+
76+
export async function resolveOciSource(
77+
source: string,
78+
options: ResolveOciSourceOptions = {}
79+
): Promise<ResolvedOciSource> {
80+
const parsed = parseOciReference(source);
81+
const scheme = options.insecureHttp || isLocalRegistry(parsed.registry) ? "http" : "https";
82+
83+
const tempRoot = path.resolve(options.tempRoot ?? os.tmpdir());
84+
fs.mkdirSync(tempRoot, { recursive: true });
85+
const workDir = fs.mkdtempSync(path.join(tempRoot, "skillet-oci-"));
86+
87+
const manifestUrl = `${scheme}://${parsed.registry}/v2/${parsed.repository}/manifests/${parsed.reference}`;
88+
const manifestResponse = await fetchWithErrors(manifestUrl, {
89+
headers: {
90+
Accept: "application/vnd.oci.image.manifest.v1+json, application/vnd.oci.artifact.manifest.v1+json",
91+
},
92+
});
93+
94+
const manifestText = await manifestResponse.text();
95+
let manifest: unknown;
96+
try {
97+
manifest = JSON.parse(manifestText);
98+
} catch {
99+
throw new OciResolveError("Manifest response was not valid JSON");
100+
}
101+
102+
if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
103+
throw new OciResolveError("Manifest body must be a JSON object");
104+
}
105+
106+
const manifestRecord = manifest as Record<string, unknown>;
107+
const artifactType = manifestRecord.artifactType;
108+
if (artifactType !== SKILLET_ARTIFACT_TYPE) {
109+
throw new OciResolveError(`Unsupported OCI artifact type: ${String(artifactType ?? "missing")}`);
110+
}
111+
112+
const layers = manifestRecord.layers;
113+
if (!Array.isArray(layers) || layers.length === 0) {
114+
throw new OciResolveError("Manifest must include at least one layer");
115+
}
116+
117+
const firstLayer = layers[0];
118+
if (!firstLayer || typeof firstLayer !== "object" || Array.isArray(firstLayer)) {
119+
throw new OciResolveError("Manifest layer entry is invalid");
120+
}
121+
122+
const layerDigest = (firstLayer as Record<string, unknown>).digest;
123+
if (typeof layerDigest !== "string" || !layerDigest.startsWith("sha256:")) {
124+
throw new OciResolveError("Manifest layer digest is invalid");
125+
}
126+
127+
const blobUrl = `${scheme}://${parsed.registry}/v2/${parsed.repository}/blobs/${layerDigest}`;
128+
const blobResponse = await fetchWithErrors(blobUrl);
129+
const blobBuffer = Buffer.from(await blobResponse.arrayBuffer());
130+
131+
const archivePath = path.join(workDir, "layer.tar");
132+
fs.writeFileSync(archivePath, blobBuffer);
133+
134+
const tarEntries = listTarEntries(archivePath);
135+
for (const entry of tarEntries) {
136+
validateTarEntry(entry);
137+
}
138+
139+
const extractPath = path.join(workDir, "extract");
140+
fs.mkdirSync(extractPath, { recursive: true });
141+
runTar(["-xf", archivePath, "-C", extractPath], "Failed to extract OCI layer tar");
142+
143+
const skillPaths = findSkillDirectories(extractPath);
144+
if (skillPaths.length !== 1) {
145+
throw new OciResolveError(`OCI artifact must contain exactly one skill, found ${skillPaths.length}`);
146+
}
147+
148+
const resolvedDigest =
149+
parsed.referenceType === "digest"
150+
? parsed.reference
151+
: manifestResponse.headers.get("docker-content-digest") ?? digestManifest(manifestText);
152+
153+
return {
154+
parsed,
155+
resolvedDigest,
156+
extractPath,
157+
contentPath: skillPaths[0],
158+
};
159+
}
160+
161+
async function fetchWithErrors(url: string, init?: RequestInit): Promise<Response> {
162+
let response: Response;
163+
try {
164+
response = await fetch(url, init);
165+
} catch (error) {
166+
const message = error instanceof Error ? error.message : String(error);
167+
throw new OciResolveError(`OCI request failed for ${url}: ${message}`);
168+
}
169+
170+
if (!response.ok) {
171+
throw new OciResolveError(`OCI request failed (${response.status} ${response.statusText}) for ${url}`);
172+
}
173+
174+
return response;
175+
}
176+
177+
function listTarEntries(archivePath: string): string[] {
178+
const output = runTar(["-tf", archivePath], "Failed to list OCI tar entries");
179+
return output
180+
.split(/\r?\n/)
181+
.map((entry) => entry.trim())
182+
.filter((entry) => entry.length > 0);
183+
}
184+
185+
function validateTarEntry(entry: string): void {
186+
const normalized = entry.replace(/\\/g, "/");
187+
if (normalized.startsWith("/") || /^[a-zA-Z]:/.test(normalized)) {
188+
throw new OciResolveError(`Unsafe absolute path in OCI layer: ${entry}`);
189+
}
190+
191+
const safe = path.posix.normalize(normalized);
192+
if (safe === ".." || safe.startsWith("../") || safe.includes("/../")) {
193+
throw new OciResolveError(`Unsafe traversal path in OCI layer: ${entry}`);
194+
}
195+
}
196+
197+
function runTar(args: string[], errorPrefix: string): string {
198+
try {
199+
return execFileSync("tar", args, {
200+
encoding: "utf8",
201+
stdio: ["ignore", "pipe", "pipe"],
202+
}).trim();
203+
} catch (error) {
204+
const stderr =
205+
error instanceof Error && "stderr" in error && typeof error.stderr === "string"
206+
? error.stderr.trim()
207+
: "";
208+
const details = stderr ? `: ${stderr}` : "";
209+
throw new OciResolveError(`${errorPrefix}${details}`);
210+
}
211+
}
212+
213+
function findSkillDirectories(root: string): string[] {
214+
const skillDirs = new Set<string>();
215+
const stack = [root];
216+
217+
while (stack.length > 0) {
218+
const current = stack.pop();
219+
if (!current) {
220+
continue;
221+
}
222+
223+
for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
224+
const fullPath = path.join(current, entry.name);
225+
if (entry.isDirectory()) {
226+
stack.push(fullPath);
227+
continue;
228+
}
229+
230+
if (entry.isFile() && entry.name === "SKILL.md") {
231+
skillDirs.add(path.dirname(fullPath));
232+
}
233+
}
234+
}
235+
236+
return [...skillDirs].sort((a, b) => a.localeCompare(b));
237+
}
238+
239+
function digestManifest(manifestJson: string): string {
240+
return `sha256:${crypto.createHash("sha256").update(manifestJson).digest("hex")}`;
241+
}
242+
243+
function isLocalRegistry(registry: string): boolean {
244+
return registry.startsWith("localhost") || registry.startsWith("127.0.0.1");
245+
}

0 commit comments

Comments
 (0)