@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/ref.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Image reference grammar (shaped like Docker's so a registry can be added later):
+ *
+ *   [registry-host[:port]/]name[:tag][@sha256:<64 hex>]
+ *
+ * name   = component ('/' component)*, component = [a-z0-9]+([._-][a-z0-9]+)*
+ * tag    = [A-Za-z0-9_][A-Za-z0-9_.-]{0,127}   (default `latest`)
+ * The first path component is a registry host when it contains '.' or ':' or is
+ * `localhost` and something follows it.
+ *
+ * A reference with a registry host names an image on that registry; locally it is just a tag
+ * (`sitefile tag blog:1 localhost:5000/blog:1`), so the store keys it as `registry/name:tag`.
+ * Docker Hub aliases (`docker.io`, `index.docker.io`, `registry-1.docker.io`) are one registry,
+ * and a Hub name without a namespace lives in `library/`. A reference with NO registry host is
+ * local everywhere except `pull` and `BASE`, which default it to Docker Hub (`nginx` is
+ * `docker.io/library/nginx`); see {@link withDefaultRegistry}.
+ */
+export interface ImageRef {
+    readonly registry: string | undefined;
+    readonly name: string;
+    /** The explicit tag, if any. */
+    readonly tag: string | undefined;
+    /** `sha256:<hex>` when the reference pins an image ID. */
+    readonly digest: string | undefined;
+}
+export declare const DEFAULT_TAG = "latest";
+export declare function parseRef(input: string): ImageRef;
+export declare const DOCKER_HUB = "docker.io";
+/** Canonical form of a reference with a registry host (Docker Hub aliases and `library/` applied). */
+export declare function canonicalRef(ref: ImageRef): ImageRef;
+/** `pull` / `BASE` semantics: a reference without a registry host means Docker Hub. */
+export declare function withDefaultRegistry(ref: ImageRef): ImageRef;
+/** The host to connect to for a (canonical) registry name. */
+export declare function registryApiHost(registry: string): string;
+/** Parse a reference that may be used as a local name or tag (a registry host is allowed). */
+export declare function parseLocalRef(input: string): ImageRef;
+/** The refs.json key of a local reference: `[registry/]name:tag`. */
+export declare function refKey(ref: ImageRef): string;
+/** Hex of at least 12 digits, optionally `sha256:`-prefixed: an image ID (prefix). */
+export declare function looksLikeImageId(s: string): boolean;

package/lib/src/ref.js

@@ -0,0 +1,79 @@
+import { SitefileError } from './errors.js';
+const COMPONENT = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+const TAG = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
+const HOST = /^(?:[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?|\[[0-9A-Fa-f:]+\])(?::[0-9]{1,5})?$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+export const DEFAULT_TAG = 'latest';
+function bad(ref, why) {
+    return new SitefileError('E_USAGE', `invalid image reference '${ref}': ${why}`);
+}
+export function parseRef(input) {
+    if (input === '')
+        throw bad(input, 'empty reference');
+    let rest = input;
+    let digest;
+    const at = rest.indexOf('@');
+    if (at !== -1) {
+        digest = rest.slice(at + 1);
+        rest = rest.slice(0, at);
+        if (!DIGEST.test(digest))
+            throw bad(input, "the digest must be 'sha256:' followed by 64 lowercase hex digits");
+    }
+    let tag;
+    const lastSlash = rest.lastIndexOf('/');
+    const colon = rest.indexOf(':', lastSlash + 1);
+    if (colon !== -1) {
+        tag = rest.slice(colon + 1);
+        rest = rest.slice(0, colon);
+        if (!TAG.test(tag))
+            throw bad(input, `invalid tag '${tag}' (letters, digits, '_', '.', '-'; at most 128 characters)`);
+    }
+    const parts = rest.split('/');
+    let registry;
+    const first = parts[0] ?? '';
+    if (parts.length > 1 && (first.includes('.') || first.includes(':') || first === 'localhost')) {
+        if (!HOST.test(first))
+            throw bad(input, `invalid registry host '${first}'`);
+        registry = first;
+        parts.shift();
+    }
+    const name = parts.join('/');
+    if (name === '' || name.length > 255)
+        throw bad(input, 'the name must be 1-255 characters');
+    for (const c of parts) {
+        if (!COMPONENT.test(c)) {
+            throw bad(input, `invalid name component '${c}' (lowercase letters and digits separated by '.', '_' or '-')`);
+        }
+    }
+    return { registry, name, tag, digest };
+}
+const DOCKER_HUB_ALIASES = new Set(['docker.io', 'index.docker.io', 'registry-1.docker.io']);
+export const DOCKER_HUB = 'docker.io';
+/** Canonical form of a reference with a registry host (Docker Hub aliases and `library/` applied). */
+export function canonicalRef(ref) {
+    if (ref.registry === undefined || !DOCKER_HUB_ALIASES.has(ref.registry.toLowerCase()))
+        return ref;
+    return { ...ref, registry: DOCKER_HUB, name: ref.name.includes('/') ? ref.name : `library/${ref.name}` };
+}
+/** `pull` / `BASE` semantics: a reference without a registry host means Docker Hub. */
+export function withDefaultRegistry(ref) {
+    return canonicalRef(ref.registry === undefined ? { ...ref, registry: DOCKER_HUB } : ref);
+}
+/** The host to connect to for a (canonical) registry name. */
+export function registryApiHost(registry) {
+    return registry === DOCKER_HUB ? 'registry-1.docker.io' : registry;
+}
+/** Parse a reference that may be used as a local name or tag (a registry host is allowed). */
+export function parseLocalRef(input) {
+    return canonicalRef(parseRef(input));
+}
+/** The refs.json key of a local reference: `[registry/]name:tag`. */
+export function refKey(ref) {
+    const c = canonicalRef(ref);
+    return `${c.registry === undefined ? '' : `${c.registry}/`}${c.name}:${c.tag ?? DEFAULT_TAG}`;
+}
+/** Hex of at least 12 digits, optionally `sha256:`-prefixed: an image ID (prefix). */
+export function looksLikeImageId(s) {
+    return /^(?:sha256:)?[0-9a-f]{12,64}$/.test(s);
+}
+//# sourceMappingURL=ref.js.map

package/lib/src/registry-auth.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Registry credentials. Sources, first match wins:
+ *
+ *   1. explicit  (`--username` + `--password-stdin`; applies only to the registry the command names)
+ *   2. $SITEFILE_REGISTRY_AUTH   JSON: { "<host>": "user:password" | {"username","password"} | {"identitytoken"} }
+ *   3. Docker config ($DOCKER_CONFIG/config.json or ~/.docker/config.json):
+ *        credHelpers[<host>]            -> docker-credential-<name> get
+ *        auths[<host>].auth|username/password|identitytoken
+ *        credsStore                     -> docker-credential-<name> get
+ *
+ * Running a credential helper executes a program, so it happens only when the config names one
+ * (the name must be a plain word, it is run without a shell, the registry URL goes to its stdin, and
+ * nothing secret is ever on argv). Secrets are returned to the caller and never logged or put in an
+ * error message.
+ */
+export interface Credentials {
+    readonly username?: string;
+    readonly password?: string;
+    /** A Docker "identity token" (OAuth2 refresh token), exchanged at the token endpoint. */
+    readonly identityToken?: string;
+}
+export interface CredentialOptions {
+    readonly explicit?: Credentials | undefined;
+    readonly env?: NodeJS.ProcessEnv;
+    /** Helper timeout (ms). */
+    readonly helperTimeoutMs?: number;
+}
+export declare function dockerConfigPath(env: NodeJS.ProcessEnv): string;
+/** Docker's `docker-credential-<name> get`: the server URL on stdin, JSON on stdout. */
+export declare function runCredentialHelper(name: string, serverUrl: string, env: NodeJS.ProcessEnv, timeoutMs: number): Promise<Credentials | undefined>;
+/** Resolve credentials for `registry` (canonical host, e.g. `docker.io` or `localhost:5000`), or undefined for anonymous access. */
+export declare function resolveCredentials(registry: string, options?: CredentialOptions): Promise<Credentials | undefined>;

package/lib/src/registry-auth.js

@@ -0,0 +1,151 @@
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SitefileError } from './errors.js';
+const DOCKER_HUB_KEYS = ['docker.io', 'index.docker.io', 'registry-1.docker.io'];
+/** `https://index.docker.io/v1/`, `registry.example.com:5000/x` -> host key. */
+function hostKey(k) {
+    const noScheme = k.replace(/^[a-z]+:\/\//i, '');
+    const host = (noScheme.split('/')[0] ?? '').toLowerCase();
+    return DOCKER_HUB_KEYS.includes(host) ? 'docker.io' : host;
+}
+/** Names under which a registry may appear in a docker config. */
+function matches(configKey, registry) {
+    return hostKey(configKey) === hostKey(registry);
+}
+export function dockerConfigPath(env) {
+    const dir = env.DOCKER_CONFIG;
+    return path.join(dir !== undefined && dir !== '' ? dir : path.join(os.homedir(), '.docker'), 'config.json');
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === 'string' && v !== '' ? v : undefined;
+}
+function fromEntry(e) {
+    if (typeof e === 'string') {
+        const i = e.indexOf(':');
+        return i > 0 ? { username: e.slice(0, i), password: e.slice(i + 1) } : undefined;
+    }
+    if (!isRecord(e))
+        return undefined;
+    const auth = str(e.auth);
+    if (auth) {
+        const text = Buffer.from(auth, 'base64').toString('utf8');
+        const i = text.indexOf(':');
+        if (i > 0)
+            return { username: text.slice(0, i), password: text.slice(i + 1) };
+    }
+    const identityToken = str(e.identitytoken) ?? str(e.identityToken);
+    if (identityToken)
+        return { identityToken, ...(str(e.username) ? { username: str(e.username) } : {}) };
+    const username = str(e.username);
+    const password = str(e.password);
+    if (username && password)
+        return { username, password };
+    return undefined;
+}
+/** Docker's `docker-credential-<name> get`: the server URL on stdin, JSON on stdout. */
+export function runCredentialHelper(name, serverUrl, env, timeoutMs) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name)) {
+        throw new SitefileError('E_AUTH', `refusing to run credential helper with unusual name '${name.slice(0, 40)}'`);
+    }
+    return new Promise((resolve, reject) => {
+        const child = execFile(`docker-credential-${name}`, ['get'], { env, timeout: timeoutMs, maxBuffer: 1 << 20, windowsHide: true }, (err, stdout) => {
+            if (err) {
+                // The helper protocol's "no entry for this server" answer means anonymous access.
+                if (typeof stdout === 'string' && /credentials not found/i.test(stdout)) {
+                    resolve(undefined);
+                    return;
+                }
+                // Deliberately no stdout/stderr: it may contain the secret.
+                const code = err.code;
+                reject(new SitefileError('E_AUTH', code === 'ENOENT'
+                    ? `credential helper docker-credential-${name} (named in your Docker config) was not found on PATH`
+                    : `credential helper docker-credential-${name} failed`));
+                return;
+            }
+            try {
+                const j = JSON.parse(stdout);
+                const user = str(j.Username);
+                const secret = str(j.Secret);
+                if (user === '<token>' && secret)
+                    resolve({ identityToken: secret });
+                else
+                    resolve(user && secret ? { username: user, password: secret } : undefined);
+            }
+            catch {
+                reject(new SitefileError('E_AUTH', `credential helper docker-credential-${name} returned unreadable output`));
+            }
+        });
+        child.stdin?.on('error', () => undefined);
+        child.stdin?.end(serverUrl);
+    });
+}
+async function readJson(file) {
+    let text;
+    try {
+        text = await fs.readFile(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return undefined;
+        throw new SitefileError('E_AUTH', `cannot read ${file}: ${e.message}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new SitefileError('E_AUTH', `${file} is not valid JSON`);
+    }
+}
+/** Resolve credentials for `registry` (canonical host, e.g. `docker.io` or `localhost:5000`), or undefined for anonymous access. */
+export async function resolveCredentials(registry, options = {}) {
+    if (options.explicit)
+        return options.explicit;
+    const env = options.env ?? process.env;
+    const raw = env.SITEFILE_REGISTRY_AUTH;
+    if (raw !== undefined && raw !== '') {
+        let j;
+        try {
+            j = JSON.parse(raw);
+        }
+        catch {
+            throw new SitefileError('E_AUTH', 'SITEFILE_REGISTRY_AUTH must be a JSON object mapping registry hosts to "user:password"');
+        }
+        if (!isRecord(j))
+            throw new SitefileError('E_AUTH', 'SITEFILE_REGISTRY_AUTH must be a JSON object mapping registry hosts to "user:password"');
+        for (const [k, v] of Object.entries(j)) {
+            if (matches(k, registry)) {
+                const c = fromEntry(v);
+                if (c)
+                    return c;
+            }
+        }
+    }
+    const cfg = await readJson(dockerConfigPath(env));
+    if (!isRecord(cfg))
+        return undefined;
+    const timeout = options.helperTimeoutMs ?? 15_000;
+    const serverUrl = hostKey(registry) === 'docker.io' ? 'https://index.docker.io/v1/' : hostKey(registry);
+    const helpers = isRecord(cfg.credHelpers) ? cfg.credHelpers : {};
+    for (const [k, v] of Object.entries(helpers)) {
+        if (matches(k, registry) && str(v))
+            return runCredentialHelper(str(v), serverUrl, env, timeout);
+    }
+    const auths = isRecord(cfg.auths) ? cfg.auths : {};
+    for (const [k, v] of Object.entries(auths)) {
+        if (matches(k, registry)) {
+            const c = fromEntry(v);
+            if (c)
+                return c;
+        }
+    }
+    const store = str(cfg.credsStore);
+    if (store)
+        return runCredentialHelper(store, serverUrl, env, timeout);
+    return undefined;
+}
+//# sourceMappingURL=registry-auth.js.map

package/lib/src/registry-cache.d.ts

@@ -0,0 +1,71 @@
+import { type ImageRef } from './ref.js';
+import type { RegistryClient } from './registry.js';
+import type { CacheEntry, RemoteCache } from './plugins/cache.js';
+/**
+ * TRANSFORM cache shared through an OCI registry (`build --cache-from <ref>` / `--cache-to <ref>`,
+ * docs/CLI.md "Registry cache"). The cache is one OCI artifact:
+ *
+ *   manifest  application/vnd.oci.image.manifest.v1+json, artifactType CACHE_ARTIFACT_TYPE,
+ *             config = the empty descriptor ({}), layers = [index, ...result blobs by digest]
+ *   index     CACHE_INDEX_MEDIA: canonical JSON {"entries":{"<key>":{"files":[[path,hex,size]],"kind":k}},"version":1}
+ *   blobs     CACHE_BLOB_MEDIA: result bytes, exactly as in the local cache's blobs/ directory
+ *
+ * `--cache-from` reads the manifest and the index before the build; a result's blobs are fetched
+ * only on a hit (a local miss whose key is in the index), verified, and written to the local cache.
+ * `--cache-to` pushes, after a successful build, the entries this build used or wrote; blobs the
+ * registry already has are not uploaded again. A registry problem is a warning, never a build failure.
+ * Pushed bytes are deterministic and hold no local paths or secrets: keys are SHA-256 hashes, entries
+ * name output-relative paths, digests and sizes only.
+ *
+ * Kept byte-for-byte in step with rust/src/registry_cache.rs.
+ */
+export declare const CACHE_ARTIFACT_TYPE = "application/vnd.sitefile.cache.v1+json";
+export declare const CACHE_INDEX_MEDIA = "application/vnd.sitefile.cache.index.v1+json";
+export declare const CACHE_BLOB_MEDIA = "application/vnd.sitefile.cache.blob.v1";
+export declare const EMPTY_MEDIA = "application/vnd.oci.empty.v1+json";
+/** Largest cache index accepted. */
+export declare const MAX_INDEX_BYTES: number;
+export interface CacheRef {
+    /** As written on the command line (used in messages). */
+    readonly input: string;
+    readonly ref: ImageRef;
+}
+/** Validate a `--cache-from` / `--cache-to` reference (E_USAGE when it is not usable). */
+export declare function parseCacheRef(flag: '--cache-from' | '--cache-to', input: string): CacheRef;
+export interface RegistryCacheOptions {
+    readonly from: readonly CacheRef[];
+    readonly to?: CacheRef | undefined;
+    /** A client for a canonical registry name (auth, TLS and network policy are the client's). */
+    readonly client: (registry: string) => RegistryClient;
+    /** $SITEFILE_CACHE_MAX in bytes (0: no limit): a build never fetches more than this. */
+    readonly limit: number;
+    readonly warn: (message: string) => void;
+    readonly notice: (message: string) => void;
+}
+/** Parse and validate an index; every blob it names must be a layer of the manifest with that size. */
+export declare function parseCacheIndex(bytes: Uint8Array, blobs: ReadonlyMap<string, number>): Map<string, CacheEntry>;
+/** The index bytes for a set of entries (canonical JSON, keys sorted). */
+export declare function encodeCacheIndex(entries: ReadonlyMap<string, CacheEntry>): Buffer;
+/** The artifact manifest for an index and the result blobs (`[hex, size]`, any order). */
+export declare function encodeCacheManifest(index: Uint8Array, blobs: ReadonlyArray<readonly [string, number]>): Buffer;
+export declare class RegistryCache implements RemoteCache {
+    private readonly o;
+    /** Entries this build used or wrote (what `--cache-to` pushes). */
+    readonly usedEntries: Map<string, CacheEntry>;
+    /** Results fetched from `--cache-from` registries, and their blob bytes downloaded. */
+    fetched: number;
+    fetchedBytes: number;
+    private readonly sources;
+    private stopped;
+    constructor(o: RegistryCacheOptions);
+    /** Read every `--cache-from` manifest and index (in order). Problems are warnings. */
+    load(): Promise<void>;
+    private loadOne;
+    used(key: string, entry: CacheEntry): void;
+    fetch(key: string, blobPath: (hex: string) => string): Promise<CacheEntry | undefined>;
+    /** Stream a result blob into the local cache: verified size and digest, temp file + rename. */
+    private download;
+    /** Push the used entries to `--cache-to` (after a successful build). Problems are warnings. */
+    push(cacheDir: string): Promise<void>;
+    private pushTo;
+}