@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/registry.d.ts

@@ -0,0 +1,109 @@
+import type { Readable } from 'node:stream';
+import { type Descriptor } from './oci.js';
+import type { Credentials } from './registry-auth.js';
+/**
+ * Client for the OCI distribution API (distribution-spec v1.1): `/v2/` probe, Bearer-token and Basic
+ * auth, manifest and blob GET/HEAD, monolithic blob upload, cross-repository mount, manifest PUT.
+ *
+ * Transport policy (the registry host is named by the user, so its address may be private):
+ *   - https, except for loopback registries (`localhost`, 127.0.0.0/8, ::1) and hosts passed as
+ *     insecure registries, which try https first and fall back to http;
+ *   - redirects are followed manually (GET/HEAD only), at most 5, every hop re-validated. Registries
+ *     redirect blob downloads to a CDN: a target on another origin must be https (unless both the
+ *     registry and the target are loopback), must not carry credentials in the URL, and must resolve
+ *     to public addresses (checked at connect time) unless `allowPrivateNetwork`;
+ *   - the Authorization header is sent to the registry's own origin only, never to a redirect target;
+ *   - token endpoints (the `realm` of a Bearer challenge) obey the same cross-origin rules;
+ *   - bodies are never decompressed; responses are bounded by the limits below.
+ * Tokens and passwords live in memory only and never appear in an error message.
+ */
+export interface RegistryLimits {
+    /** Largest blob accepted (bytes). */
+    readonly maxBlobBytes: number;
+    /** Largest total of all blobs of one image (bytes). */
+    readonly maxTotalBytes: number;
+    /** Largest manifest / token response (bytes). */
+    readonly maxManifestBytes: number;
+    /** Idle/connect timeout per request (ms). */
+    readonly timeoutMs: number;
+    /** Time budget for one blob transfer (ms). */
+    readonly blobDeadlineMs: number;
+}
+export declare const DEFAULT_REGISTRY_LIMITS: RegistryLimits;
+export interface RegistryOptions {
+    /** Registries (`host[:port]`) that may be reached over plain http. */
+    readonly insecureRegistries?: readonly string[] | undefined;
+    /** Let redirects and token endpoints on other origins resolve to private addresses. */
+    readonly allowPrivateNetwork?: boolean | undefined;
+    /** Asked lazily, only when the registry demands authentication. */
+    readonly credentials?: (() => Promise<Credentials | undefined>) | undefined;
+    readonly limits?: Partial<RegistryLimits> | undefined;
+    /** Extra PEM CA certificate(s) (tests / private CAs). */
+    readonly ca?: string | Buffer | undefined;
+}
+export interface Body {
+    readonly length: number;
+    readonly open: () => Readable | Uint8Array;
+}
+export declare const MANIFEST_ACCEPT: string;
+export interface ManifestResponse {
+    readonly bytes: Uint8Array;
+    readonly digest: string;
+    readonly mediaType: string;
+}
+export declare function isLoopbackHost(hostname: string): boolean;
+export declare class RegistryClient {
+    readonly registry: string;
+    private readonly options;
+    readonly limits: RegistryLimits;
+    private origin;
+    private readonly insecure;
+    private readonly loopback;
+    private readonly host;
+    private readonly tokens;
+    private creds;
+    /** `registry` is the canonical registry name (`docker.io`, `ghcr.io`, `localhost:5000`). */
+    constructor(registry: string, options?: RegistryOptions);
+    private sameOrigin;
+    /** Refuse hops that leave the registry's origin unless they are safe. */
+    private checkTarget;
+    private sendOnce;
+    /** One logical request: follows redirects (GET/HEAD) re-validating each hop; auth only at the registry origin. */
+    private follow;
+    /** Find the base URL: https, or (insecure registries only) http when https is unreachable. */
+    private init;
+    private getCreds;
+    private fetchToken;
+    private authenticate;
+    /** Send a request, answering a 401 challenge (anonymous token first, then credentials). */
+    private call;
+    private v2;
+    private fail;
+    private repoPath;
+    /** `GET /v2/`: confirms the endpoint speaks the distribution API (authenticating if it demands it). */
+    ping(): Promise<void>;
+    getManifest(repo: string, reference: string): Promise<ManifestResponse>;
+    /**
+     * `GET /v2/<repo>/tags/list`, following `Link: <...>; rel="next"` pages on this registry (at most
+     * 10 pages of 1000). Tags that are not valid tag names are dropped.
+     */
+    listTags(repo: string): Promise<string[]>;
+    hasBlob(repo: string, digest: string): Promise<boolean>;
+    /** Stream a blob's bytes (redirects followed under the policy above). The caller verifies size and digest. */
+    getBlob(repo: string, desc: Descriptor): AsyncGenerator<Buffer>;
+    /**
+     * Make a blob exist in `repo`: tries a cross-repository mount from `mountFrom` (same registry) when
+     * given, else a monolithic upload (POST then PUT).
+     */
+    pushBlob(repo: string, desc: Descriptor, body: Body, mountFrom?: string): Promise<'mounted' | 'uploaded'>;
+    /** `PUT` a manifest at a tag or digest; returns the digest the registry confirms. */
+    putManifest(repo: string, reference: string, bytes: Uint8Array, mediaType: string): Promise<string>;
+    /**
+     * {@link putManifest}, also returning the `OCI-Subject` response header: a registry that implements
+     * the referrers API sets it when the manifest has a `subject` (distribution spec v1.1).
+     */
+    putManifestFull(repo: string, reference: string, bytes: Uint8Array, mediaType: string): Promise<{
+        digest: string;
+        subject: string | undefined;
+    }>;
+}

package/lib/src/registry.js

@@ -0,0 +1,505 @@
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { isIP } from 'node:net';
+import { pipeline } from 'node:stream/promises';
+import * as tls from 'node:tls';
+import { sha256 } from './digest.js';
+import { SitefileError, isSitefileError } from './errors.js';
+import { MEDIA } from './oci.js';
+import { registryApiHost } from './ref.js';
+import { createGuardedLookup, redactUrl } from './resources/https.js';
+import { isPublicAddress } from './resources/netpolicy.js';
+import { DEFAULT_FETCH_POLICY } from './resources/types.js';
+export const DEFAULT_REGISTRY_LIMITS = {
+    maxBlobBytes: 2 * 1024 ** 3,
+    maxTotalBytes: 8 * 1024 ** 3,
+    maxManifestBytes: 4 * 1024 ** 2,
+    timeoutMs: 30_000,
+    blobDeadlineMs: 30 * 60_000,
+};
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 5;
+const NAME_RE = /^[a-z0-9]+(?:[._-][a-z0-9]+)*(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)*$/;
+const REF_RE = /^(?:[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}|sha256:[0-9a-f]{64})$/;
+const TAG_RE = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
+export const MANIFEST_ACCEPT = [MEDIA.manifest, MEDIA.index, MEDIA.dockerManifest, MEDIA.dockerList].join(', ');
+function hostnameOf(hostPort) {
+    if (hostPort.startsWith('['))
+        return hostPort.slice(1, hostPort.indexOf(']'));
+    return hostPort.replace(/:\d+$/, '');
+}
+export function isLoopbackHost(hostname) {
+    const h = hostname.toLowerCase();
+    return h === 'localhost' || h.endsWith('.localhost') || h === '::1' || /^127\.\d+\.\d+\.\d+$/.test(h);
+}
+function unwrap(e, depth = 0) {
+    if (depth > 4 || e === null || typeof e !== 'object')
+        return undefined;
+    if (isSitefileError(e))
+        return e;
+    const x = e;
+    if (Array.isArray(x.errors))
+        for (const i of x.errors) {
+            const f = unwrap(i, depth + 1);
+            if (f)
+                return f;
+        }
+    return unwrap(x.cause, depth + 1);
+}
+function parseChallenge(header) {
+    const h = Array.isArray(header) ? header[0] : header;
+    if (!h)
+        return undefined;
+    const m = /^\s*([A-Za-z]+)\s*(.*)$/s.exec(h);
+    if (!m)
+        return undefined;
+    const params = {};
+    for (const p of (m[2] ?? '').matchAll(/([A-Za-z_]+)="([^"]*)"/g))
+        params[p[1].toLowerCase()] = p[2];
+    return { scheme: m[1].toLowerCase(), params };
+}
+async function readBody(res, max) {
+    const chunks = [];
+    let n = 0;
+    try {
+        for await (const c of res) {
+            n += c.length;
+            if (n > max) {
+                res.destroy();
+                throw new SitefileError('E_TOO_LARGE', `registry response exceeded ${max} bytes`);
+            }
+            chunks.push(c);
+        }
+    }
+    catch (e) {
+        if (isSitefileError(e))
+            throw e;
+        throw new SitefileError('E_REGISTRY', `error reading registry response: ${e.message}`, undefined, { cause: e });
+    }
+    return Buffer.concat(chunks, n);
+}
+function clean(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, 200);
+}
+export class RegistryClient {
+    registry;
+    options;
+    limits;
+    origin;
+    insecure;
+    loopback;
+    host;
+    tokens = new Map();
+    creds;
+    /** `registry` is the canonical registry name (`docker.io`, `ghcr.io`, `localhost:5000`). */
+    constructor(registry, options = {}) {
+        this.registry = registry;
+        this.options = options;
+        this.host = registryApiHost(registry);
+        this.limits = { ...DEFAULT_REGISTRY_LIMITS, ...options.limits };
+        this.loopback = isLoopbackHost(hostnameOf(this.host));
+        this.insecure = this.loopback || (options.insecureRegistries ?? []).some((h) => h.toLowerCase() === this.host.toLowerCase() || h.toLowerCase() === registry.toLowerCase());
+    }
+    // ------------------------------------------------------------ transport
+    sameOrigin(u) {
+        return this.origin !== undefined && u.protocol === this.origin.protocol && u.host === this.origin.host;
+    }
+    /** Refuse hops that leave the registry's origin unless they are safe. */
+    checkTarget(u) {
+        if (this.sameOrigin(u))
+            return;
+        const host = u.hostname.replace(/^\[|\]$/g, '');
+        if (u.username !== '' || u.password !== '')
+            throw new SitefileError('E_PROTOCOL', `refusing a URL with credentials (${redactUrl(u)})`);
+        const loopbackPair = this.loopback && isLoopbackHost(host);
+        if (u.protocol !== 'https:' && !(u.protocol === 'http:' && loopbackPair)) {
+            throw new SitefileError('E_PROTOCOL', `${this.registry}: refusing to follow a redirect or token realm to ${redactUrl(u)}: it must use https`);
+        }
+        if (isIP(host) !== 0 && !isPublicAddress(host) && !this.options.allowPrivateNetwork && !loopbackPair) {
+            throw new SitefileError('E_SSRF_BLOCKED', `${this.registry}: refusing to connect to non-public address ${host} (${redactUrl(u)}); use --allow-private-network to permit it`);
+        }
+    }
+    sendOnce(method, url, headers, body, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const same = this.sameOrigin(url);
+            const host = url.hostname.replace(/^\[|\]$/g, '');
+            const loopbackPair = this.loopback && isLoopbackHost(host);
+            const policy = { ...DEFAULT_FETCH_POLICY, allowPrivateNetwork: same || loopbackPair || !!this.options.allowPrivateNetwork };
+            const h = { 'accept-encoding': 'identity', 'user-agent': 'sitefile/0.1', ...headers };
+            if (body)
+                h['content-length'] = String(body.length);
+            const o = { method, headers: h, lookup: createGuardedLookup(policy), agent: false, timeout: timeoutMs };
+            if (url.protocol === 'https:' && this.options.ca !== undefined) {
+                const get = tls.getCACertificates;
+                o.ca = [...(get ? get('default') : tls.rootCertificates), this.options.ca];
+            }
+            let req;
+            try {
+                req = (url.protocol === 'https:' ? httpsRequest : httpRequest)(url, o);
+            }
+            catch (e) {
+                reject(new SitefileError('E_REGISTRY', `cannot request ${redactUrl(url)}: ${e.message}`, undefined, { cause: e }));
+                return;
+            }
+            req.on('timeout', () => req.destroy(new SitefileError('E_FETCH_TIMEOUT', `${method} ${redactUrl(url)} timed out after ${timeoutMs} ms`)));
+            req.on('response', resolve);
+            req.on('error', (e) => reject(unwrap(e) ?? new SitefileError('E_REGISTRY', `${method} ${redactUrl(url)} failed: ${e.message}`, undefined, { cause: e })));
+            if (!body) {
+                req.end();
+                return;
+            }
+            const data = body.open();
+            if (data instanceof Uint8Array)
+                req.end(data);
+            else
+                pipeline(data, req).catch((e) => req.destroy(e));
+        });
+    }
+    /** One logical request: follows redirects (GET/HEAD) re-validating each hop; auth only at the registry origin. */
+    async follow(method, url, headers, body, auth, timeoutMs) {
+        let cur = url;
+        for (let hops = 0;; hops++) {
+            this.checkTarget(cur);
+            const h = { ...headers };
+            if (auth && this.sameOrigin(cur))
+                h.authorization = auth;
+            const res = await this.sendOnce(method, cur, h, body, timeoutMs);
+            const status = res.statusCode ?? 0;
+            if (!REDIRECTS.has(status) || (method !== 'GET' && method !== 'HEAD'))
+                return res;
+            const loc = res.headers.location;
+            res.resume();
+            if (!loc)
+                throw new SitefileError('E_REDIRECT', `redirect ${status} from ${redactUrl(cur)} has no Location header`);
+            if (hops >= MAX_REDIRECTS)
+                throw new SitefileError('E_REDIRECT', `too many redirects from ${redactUrl(url)} (limit ${MAX_REDIRECTS})`);
+            try {
+                cur = new URL(loc, cur);
+            }
+            catch (e) {
+                throw new SitefileError('E_REDIRECT', `invalid redirect Location from ${redactUrl(cur)}`, undefined, { cause: e });
+            }
+        }
+    }
+    /** Find the base URL: https, or (insecure registries only) http when https is unreachable. */
+    async init() {
+        if (this.origin)
+            return this.origin;
+        const https = new URL(`https://${this.host}/`);
+        if (!this.insecure) {
+            this.origin = https;
+            return https;
+        }
+        this.origin = https;
+        try {
+            const r = await this.sendOnce('GET', new URL('/v2/', https), {}, undefined, Math.min(5000, this.limits.timeoutMs));
+            r.resume();
+            return https;
+        }
+        catch (e) {
+            if (isSitefileError(e) && e.code !== 'E_REGISTRY' && e.code !== 'E_FETCH_TIMEOUT')
+                throw e;
+            this.origin = new URL(`http://${this.host}/`);
+            return this.origin;
+        }
+    }
+    async getCreds() {
+        this.creds ??= { value: await this.options.credentials?.() };
+        return this.creds.value;
+    }
+    // ------------------------------------------------------------ auth
+    async fetchToken(chal, scope, creds) {
+        const realm = chal.params.realm;
+        let url;
+        try {
+            url = new URL(realm ?? '');
+        }
+        catch {
+            throw new SitefileError('E_AUTH', `${this.registry}: the registry's token challenge has no usable realm`);
+        }
+        if (chal.params.service)
+            url.searchParams.set('service', chal.params.service);
+        for (const s of scope.split(' ').filter(Boolean))
+            url.searchParams.append('scope', s);
+        const headers = { accept: 'application/json' };
+        let method = 'GET';
+        let body;
+        if (creds?.identityToken) {
+            method = 'POST';
+            const form = Buffer.from(new URLSearchParams({ grant_type: 'refresh_token', service: chal.params.service ?? '', scope, client_id: 'sitefile', refresh_token: creds.identityToken }).toString());
+            url.search = '';
+            headers['content-type'] = 'application/x-www-form-urlencoded';
+            body = { length: form.length, open: () => form };
+        }
+        else if (creds?.username && creds.password !== undefined) {
+            headers.authorization = `Basic ${Buffer.from(`${creds.username}:${creds.password}`).toString('base64')}`;
+        }
+        const res = await this.follow(method, url, headers, body, undefined, this.limits.timeoutMs);
+        if (res.statusCode !== 200) {
+            res.resume();
+            const s = res.statusCode ?? 0;
+            throw new SitefileError('E_AUTH', `${this.registry}: the token endpoint ${redactUrl(url)} answered HTTP ${s}${s === 401 || s === 403 ? ' (credentials rejected or missing)' : ''}`);
+        }
+        let j;
+        try {
+            j = JSON.parse((await readBody(res, this.limits.maxManifestBytes)).toString('utf8'));
+        }
+        catch (e) {
+            if (isSitefileError(e))
+                throw e;
+            throw new SitefileError('E_AUTH', `${this.registry}: the token endpoint returned unreadable output`);
+        }
+        const token = typeof j.token === 'string' && j.token !== '' ? j.token : typeof j.access_token === 'string' && j.access_token !== '' ? j.access_token : undefined;
+        if (!token)
+            throw new SitefileError('E_AUTH', `${this.registry}: the token endpoint returned no token`);
+        return token;
+    }
+    async authenticate(chal, scope, useCreds) {
+        const needCreds = useCreds || chal.scheme === 'basic';
+        const creds = needCreds ? await this.getCreds() : undefined;
+        if (needCreds && !creds) {
+            throw new SitefileError('E_AUTH', `${this.registry}: authentication required but no credentials were found (use "docker login ${this.registry}", $SITEFILE_REGISTRY_AUTH, or --username with --password-stdin)`);
+        }
+        if (chal.scheme === 'basic') {
+            if (!creds?.username || creds.password === undefined)
+                throw new SitefileError('E_AUTH', `${this.registry}: Basic authentication needs a username and password`);
+            return `Basic ${Buffer.from(`${creds.username}:${creds.password}`).toString('base64')}`;
+        }
+        if (chal.scheme === 'bearer')
+            return `Bearer ${await this.fetchToken(chal, chal.params.scope || scope, creds)}`;
+        throw new SitefileError('E_AUTH', `${this.registry}: unsupported authentication scheme '${clean(chal.scheme)}'`);
+    }
+    /** Send a request, answering a 401 challenge (anonymous token first, then credentials). */
+    async call(method, url, o) {
+        await this.init();
+        const timeout = o.timeoutMs ?? this.limits.timeoutMs;
+        let usedCreds = false;
+        for (let attempt = 0;; attempt++) {
+            const res = await this.follow(method, url, o.headers ?? {}, o.body, this.tokens.get(o.scope), timeout);
+            if (res.statusCode !== 401 || attempt >= 2)
+                return res;
+            const chal = parseChallenge(res.headers['www-authenticate']);
+            res.resume();
+            if (!chal)
+                return res;
+            // Pushing needs credentials from the start; for pulls try an anonymous token before them.
+            let wantCreds = o.scope.split(' ').some((x) => x.endsWith(',push') || x.endsWith(':push'));
+            if (attempt === 1) {
+                if (usedCreds)
+                    throw new SitefileError('E_AUTH', `${this.registry}: access denied (the credentials were rejected or lack permission)`);
+                wantCreds = true;
+            }
+            this.tokens.set(o.scope, await this.authenticate(chal, o.scope, wantCreds));
+            usedCreds = wantCreds || chal.scheme === 'basic';
+        }
+    }
+    v2(p) {
+        return new URL(`/v2/${p}`, this.origin);
+    }
+    async fail(res, what) {
+        const status = res.statusCode ?? 0;
+        let detail = '';
+        try {
+            const j = JSON.parse((await readBody(res, 64 * 1024)).toString('utf8'));
+            detail = (j.errors ?? [])
+                .slice(0, 3)
+                .map((e) => [e.code, e.message].filter((x) => typeof x === 'string').map(clean).join(': '))
+                .filter(Boolean)
+                .join('; ');
+        }
+        catch {
+            res.destroy();
+        }
+        const msg = `${this.registry}: ${what} failed: HTTP ${status}${detail ? ` (${detail})` : ''}`;
+        if (status === 401 || status === 403)
+            throw new SitefileError('E_AUTH', `${msg}; check your credentials and permissions`);
+        if (status === 404)
+            throw new SitefileError('E_NOT_FOUND', msg);
+        throw new SitefileError('E_REGISTRY', msg);
+    }
+    repoPath(repo) {
+        if (!NAME_RE.test(repo))
+            throw new SitefileError('E_USAGE', `invalid repository name '${repo}'`);
+        return repo;
+    }
+    // ------------------------------------------------------------ API
+    /** `GET /v2/`: confirms the endpoint speaks the distribution API (authenticating if it demands it). */
+    async ping() {
+        const res = await this.call('GET', new URL('/v2/', await this.init()), { scope: '' });
+        if (res.statusCode === 200) {
+            res.resume();
+            return;
+        }
+        await this.fail(res, 'GET /v2/');
+    }
+    async getManifest(repo, reference) {
+        if (!REF_RE.test(reference))
+            throw new SitefileError('E_USAGE', `invalid reference '${reference}'`);
+        await this.init();
+        const res = await this.call('GET', this.v2(`${this.repoPath(repo)}/manifests/${reference}`), { scope: `repository:${repo}:pull`, headers: { accept: MANIFEST_ACCEPT } });
+        if (res.statusCode !== 200)
+            return this.fail(res, `GET manifest ${repo}:${clean(reference)}`);
+        const bytes = new Uint8Array(await readBody(res, this.limits.maxManifestBytes));
+        const digest = sha256(bytes);
+        if (reference.startsWith('sha256:') && digest !== reference) {
+            throw new SitefileError('E_INTEGRITY', `${this.registry}/${repo}: manifest content does not match the requested digest ${reference}`);
+        }
+        const claimed = res.headers['docker-content-digest'];
+        if (typeof claimed === 'string' && claimed !== digest) {
+            throw new SitefileError('E_INTEGRITY', `${this.registry}/${repo}: manifest does not match the digest the registry reported (${clean(claimed)})`);
+        }
+        let mediaType = String(res.headers['content-type'] ?? '').split(';')[0]?.trim().toLowerCase() ?? '';
+        if (mediaType === '' || mediaType === 'application/json' || mediaType === 'text/plain') {
+            try {
+                const j = JSON.parse(Buffer.from(bytes).toString('utf8'));
+                if (typeof j.mediaType === 'string')
+                    mediaType = j.mediaType;
+            }
+            catch {
+                /* handled by the caller */
+            }
+        }
+        return { bytes, digest, mediaType };
+    }
+    /**
+     * `GET /v2/<repo>/tags/list`, following `Link: <...>; rel="next"` pages on this registry (at most
+     * 10 pages of 1000). Tags that are not valid tag names are dropped.
+     */
+    async listTags(repo) {
+        await this.init();
+        const out = [];
+        let url = this.v2(`${this.repoPath(repo)}/tags/list?n=1000`);
+        for (let page = 0; page < 10; page++) {
+            const res = await this.call('GET', url, { scope: `repository:${repo}:pull` });
+            if (res.statusCode !== 200)
+                return this.fail(res, `GET tags ${repo}`);
+            const link = res.headers.link;
+            let j;
+            try {
+                j = JSON.parse((await readBody(res, this.limits.maxManifestBytes)).toString('utf8'));
+            }
+            catch {
+                throw new SitefileError('E_REGISTRY', `${this.registry}/${repo}: the tag list is not valid JSON`);
+            }
+            for (const t of Array.isArray(j.tags) ? j.tags : [])
+                if (typeof t === 'string' && TAG_RE.test(t))
+                    out.push(t);
+            const next = typeof link === 'string' ? /<(\/v2\/[^>]*)>\s*;\s*rel="?next"?/.exec(link)?.[1] : undefined;
+            if (next === undefined)
+                break;
+            url = new URL(next, this.origin);
+        }
+        return out;
+    }
+    async hasBlob(repo, digest) {
+        await this.init();
+        const res = await this.call('HEAD', this.v2(`${this.repoPath(repo)}/blobs/${digest}`), { scope: `repository:${repo}:pull,push` });
+        res.resume();
+        if (res.statusCode === 200)
+            return true;
+        if (res.statusCode === 404)
+            return false;
+        return this.fail(res, `HEAD blob ${digest}`);
+    }
+    /** Stream a blob's bytes (redirects followed under the policy above). The caller verifies size and digest. */
+    async *getBlob(repo, desc) {
+        await this.init();
+        if (desc.size > this.limits.maxBlobBytes) {
+            throw new SitefileError('E_TOO_LARGE', `blob ${desc.digest} is ${desc.size} bytes, exceeding the limit of ${this.limits.maxBlobBytes} bytes`);
+        }
+        const res = await this.call('GET', this.v2(`${this.repoPath(repo)}/blobs/${desc.digest}`), { scope: `repository:${repo}:pull`, timeoutMs: this.limits.timeoutMs });
+        if (res.statusCode !== 200)
+            return void (await this.fail(res, `GET blob ${desc.digest}`));
+        const enc = String(res.headers['content-encoding'] ?? '').trim().toLowerCase();
+        if (enc !== '' && enc !== 'identity') {
+            res.destroy();
+            throw new SitefileError('E_REGISTRY', `${this.registry}: blob ${desc.digest} came with content-encoding '${clean(enc)}'; only identity is accepted`);
+        }
+        const declared = Number(res.headers['content-length']);
+        if (Number.isFinite(declared) && declared > desc.size) {
+            res.destroy();
+            throw new SitefileError('E_TOO_LARGE', `blob ${desc.digest}: the server sent ${declared} bytes for a ${desc.size}-byte blob`);
+        }
+        const timer = setTimeout(() => res.destroy(new SitefileError('E_FETCH_TIMEOUT', `downloading blob ${desc.digest} exceeded ${this.limits.blobDeadlineMs} ms`)), this.limits.blobDeadlineMs);
+        timer.unref?.();
+        try {
+            for await (const chunk of res)
+                yield chunk;
+        }
+        catch (e) {
+            throw unwrap(e) ?? new SitefileError('E_REGISTRY', `error downloading blob ${desc.digest}: ${e.message}`, undefined, { cause: e });
+        }
+        finally {
+            clearTimeout(timer);
+            res.destroy();
+        }
+    }
+    /**
+     * Make a blob exist in `repo`: tries a cross-repository mount from `mountFrom` (same registry) when
+     * given, else a monolithic upload (POST then PUT).
+     */
+    async pushBlob(repo, desc, body, mountFrom) {
+        await this.init();
+        const scope = `repository:${repo}:pull,push${mountFrom ? ` repository:${mountFrom}:pull` : ''}`;
+        const start = this.v2(`${this.repoPath(repo)}/blobs/uploads/`);
+        if (mountFrom) {
+            start.searchParams.set('mount', desc.digest);
+            start.searchParams.set('from', this.repoPath(mountFrom));
+        }
+        const post = await this.call('POST', start, { scope });
+        if (post.statusCode === 201) {
+            post.resume();
+            return 'mounted';
+        }
+        if (post.statusCode !== 202)
+            return this.fail(post, `start upload of ${desc.digest}`);
+        post.resume();
+        const loc = post.headers.location;
+        if (!loc)
+            throw new SitefileError('E_REGISTRY', `${this.registry}: upload response has no Location header`);
+        let target;
+        try {
+            target = new URL(loc, start);
+        }
+        catch (e) {
+            throw new SitefileError('E_REGISTRY', `${this.registry}: invalid upload Location`, undefined, { cause: e });
+        }
+        target.searchParams.set('digest', desc.digest);
+        const put = await this.call('PUT', target, { scope, headers: { 'content-type': 'application/octet-stream' }, body, timeoutMs: this.limits.blobDeadlineMs });
+        if (put.statusCode === 201 || put.statusCode === 204) {
+            put.resume();
+            return 'uploaded';
+        }
+        return this.fail(put, `upload of ${desc.digest}`);
+    }
+    /** `PUT` a manifest at a tag or digest; returns the digest the registry confirms. */
+    async putManifest(repo, reference, bytes, mediaType) {
+        return (await this.putManifestFull(repo, reference, bytes, mediaType)).digest;
+    }
+    /**
+     * {@link putManifest}, also returning the `OCI-Subject` response header: a registry that implements
+     * the referrers API sets it when the manifest has a `subject` (distribution spec v1.1).
+     */
+    async putManifestFull(repo, reference, bytes, mediaType) {
+        if (!REF_RE.test(reference))
+            throw new SitefileError('E_USAGE', `invalid reference '${reference}'`);
+        await this.init();
+        const res = await this.call('PUT', this.v2(`${this.repoPath(repo)}/manifests/${reference}`), {
+            scope: `repository:${repo}:pull,push`,
+            headers: { 'content-type': mediaType },
+            body: { length: bytes.byteLength, open: () => bytes },
+        });
+        if (res.statusCode !== 201 && res.statusCode !== 200)
+            return this.fail(res, `PUT manifest ${repo}:${clean(reference)}`);
+        res.resume();
+        const digest = sha256(bytes);
+        const claimed = res.headers['docker-content-digest'];
+        if (typeof claimed === 'string' && claimed !== digest) {
+            throw new SitefileError('E_INTEGRITY', `${this.registry}/${repo}: the registry stored the manifest as ${clean(claimed)}, expected ${digest}`);
+        }
+        const subject = res.headers['oci-subject'];
+        return { digest, subject: typeof subject === 'string' ? subject : undefined };
+    }
+}
+//# sourceMappingURL=registry.js.map