vestrycms 0.0.0-stage → 0.2.0

package/dist/core/sources/github-app.js

@@ -0,0 +1,161 @@
+/**
+ * GitHub App authentication: a short-lived RS256 JWT signed with the app's
+ * private key is exchanged for an installation access token (valid for an
+ * hour), which the GitHub source then uses like any other token. WebCrypto
+ * only, so it works in workerd as well as Node.
+ */
+import { base64Decode, base64Encode, SourceError } from "../source.js";
+const tokenCache = new Map();
+/**
+ * Returns a provider that mints (and caches) installation tokens for the
+ * app. Concurrent callers share one in-flight mint; a failed mint is
+ * forgotten so the next caller retries; tokens are renewed a minute early.
+ */
+export function installationTokenProvider(creds) {
+    const cacheKey = `${creds.apiBase ?? ""}|${creds.appId}:${creds.installationId}`;
+    const provider = async () => {
+        const entry = tokenCache.get(cacheKey);
+        if (entry && entry.expiresAt - Date.now() > 60_000) {
+            return (await entry.promise).token;
+        }
+        const fresh = {
+            expiresAt: Infinity,
+            promise: mintInstallationToken(creds),
+        };
+        tokenCache.set(cacheKey, fresh);
+        try {
+            const minted = await fresh.promise;
+            fresh.expiresAt = minted.expiresAt;
+            return minted.token;
+        }
+        catch (e) {
+            if (tokenCache.get(cacheKey) === fresh)
+                tokenCache.delete(cacheKey);
+            throw e;
+        }
+    };
+    provider.invalidate = () => {
+        tokenCache.delete(cacheKey);
+    };
+    return provider;
+}
+export async function mintInstallationToken(creds) {
+    const apiBase = (creds.apiBase ?? "https://api.github.com").replace(/\/$/, "");
+    const jwt = await signAppJwt(creds.appId, creds.privateKey);
+    const res = await fetch(`${apiBase}/app/installations/${encodeURIComponent(creds.installationId)}/access_tokens`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "vestry",
+        },
+    });
+    if (!res.ok) {
+        let detail = `${res.status}`;
+        try {
+            const body = (await res.json());
+            if (body.message)
+                detail = `${body.message} (${res.status})`;
+        }
+        catch {
+            /* ignore */
+        }
+        throw new SourceError(`Could not get a GitHub App installation token: ${detail}`, 502, "github_app");
+    }
+    const data = (await res.json());
+    return { token: data.token, expiresAt: Date.parse(data.expires_at) };
+}
+/** A GitHub App JWT: issued a minute ago (clock skew), valid for nine more. */
+export async function signAppJwt(appId, privateKey) {
+    const now = Math.floor(Date.now() / 1000);
+    const header = base64Url(new TextEncoder().encode(JSON.stringify({ alg: "RS256", typ: "JWT" })));
+    const payload = base64Url(new TextEncoder().encode(JSON.stringify({ iat: now - 60, exp: now + 9 * 60, iss: appId })));
+    const key = await importRsaPrivateKey(privateKey);
+    const signature = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, new TextEncoder().encode(`${header}.${payload}`));
+    return `${header}.${payload}.${base64Url(new Uint8Array(signature))}`;
+}
+// ----------------------------------------------------------- key handling
+export async function importRsaPrivateKey(pem) {
+    const der = pemToPkcs8(normalizePem(pem));
+    try {
+        return await crypto.subtle.importKey("pkcs8", der, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["sign"]);
+    }
+    catch (e) {
+        throw new SourceError(`The GitHub App private key could not be imported: ${e instanceof Error ? e.message : String(e)}`, 500, "github_app_key");
+    }
+}
+/** Accepts a PEM, a PEM with literal `\n`, or a base64-encoded PEM (handy for env vars). */
+function normalizePem(value) {
+    let pem = value.trim().replace(/\\n/g, "\n");
+    if (!pem.includes("-----BEGIN")) {
+        try {
+            pem = new TextDecoder().decode(base64Decode(pem)).trim();
+        }
+        catch {
+            /* fall through to the error below */
+        }
+    }
+    if (!pem.includes("-----BEGIN")) {
+        throw new SourceError("The GitHub App private key is not a PEM-encoded key.", 500, "github_app_key");
+    }
+    return pem;
+}
+/** PKCS#8 DER for the key, wrapping PKCS#1 (`RSA PRIVATE KEY`) when needed. */
+function pemToPkcs8(pem) {
+    const match = pem.match(/-----BEGIN ([A-Z ]+)-----([\s\S]+?)-----END \1-----/);
+    if (!match) {
+        throw new SourceError("The GitHub App private key PEM is malformed.", 500, "github_app_key");
+    }
+    const label = match[1];
+    const body = base64Decode(match[2]);
+    if (label === "PRIVATE KEY")
+        return body;
+    if (label === "RSA PRIVATE KEY")
+        return wrapPkcs1(body);
+    throw new SourceError(`Unsupported private key type "${label}"; expected an RSA private key.`, 500, "github_app_key");
+}
+/**
+ * PrivateKeyInfo ::= SEQUENCE { version INTEGER 0, algorithm
+ * AlgorithmIdentifier { rsaEncryption, NULL }, privateKey OCTET STRING }
+ */
+function wrapPkcs1(pkcs1) {
+    const version = new Uint8Array([0x02, 0x01, 0x00]);
+    const algorithm = new Uint8Array([
+        0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01,
+        0x01, 0x05, 0x00,
+    ]);
+    const octetString = der(0x04, pkcs1);
+    return der(0x30, concat(version, algorithm, octetString));
+}
+function der(tag, content) {
+    const len = content.length;
+    let lengthBytes;
+    if (len < 0x80)
+        lengthBytes = [len];
+    else {
+        const bytes = [];
+        let n = len;
+        while (n > 0) {
+            bytes.unshift(n & 0xff);
+            n >>= 8;
+        }
+        lengthBytes = [0x80 | bytes.length, ...bytes];
+    }
+    return concat(new Uint8Array([tag, ...lengthBytes]), content);
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let offset = 0;
+    for (const p of parts) {
+        out.set(p, offset);
+        offset += p.length;
+    }
+    return out;
+}
+function base64Url(bytes) {
+    return base64Encode(bytes)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}

package/dist/core/sources/github.d.ts

@@ -0,0 +1,40 @@
+import { type CommitInfo, type CommitOptions, type ContentSource, type FileChange, type FileData, type SourceInfo, type TreeEntry } from "../source.js";
+import { type Cache } from "../cache.js";
+import type { TokenProvider } from "./github-app.js";
+export interface GitHubSourceOptions {
+    owner: string;
+    repo: string;
+    /** Branch to read from and commit to. Resolved to the default branch when omitted. */
+    branch?: string;
+    /** A token with contents read/write access, or a provider that mints one (e.g. a GitHub App installation token). */
+    token: string | TokenProvider | (() => Promise<string>);
+    cache?: Cache;
+    apiBase?: string;
+    /** How long (seconds) to trust a cached branch head before re-checking. */
+    headTtl?: number;
+}
+/**
+ * GitHub-backed source using the Git Data API.
+ *
+ * Reads: the branch head is cached briefly (and revalidated with ETags, which
+ * don't count against the rate limit); the recursive tree is cached per tree
+ * SHA; blobs are cached per blob SHA (immutable). After one of our own commits
+ * the head cache is updated in place so the next read sees the new state
+ * without waiting for the TTL.
+ *
+ * Writes: blobs → tree (on top of the base tree) → commit → ref update, which
+ * yields a single commit per save even when assets are uploaded alongside.
+ */
+export declare class GitHubSource implements ContentSource {
+    #private;
+    private opts;
+    constructor(opts: GitHubSourceOptions);
+    info(): SourceInfo;
+    get repoPath(): string;
+    branch(): Promise<string>;
+    head(): Promise<string>;
+    list(directory: string): Promise<TreeEntry[]>;
+    readBlob(sha: string): Promise<Uint8Array>;
+    read(p: string): Promise<FileData | null>;
+    commit(changes: FileChange[], options: CommitOptions): Promise<CommitInfo>;
+}

package/dist/core/sources/github.js

@@ -0,0 +1,278 @@
+import { base64Decode, base64Encode, SourceError, toBytes, } from "../source.js";
+import { sharedMemoryCache } from "../cache.js";
+import { isSafeRepoPath, normalizePath } from "../paths.js";
+/**
+ * GitHub-backed source using the Git Data API.
+ *
+ * Reads: the branch head is cached briefly (and revalidated with ETags, which
+ * don't count against the rate limit); the recursive tree is cached per tree
+ * SHA; blobs are cached per blob SHA (immutable). After one of our own commits
+ * the head cache is updated in place so the next read sees the new state
+ * without waiting for the TTL.
+ *
+ * Writes: blobs → tree (on top of the base tree) → commit → ref update, which
+ * yields a single commit per save even when assets are uploaded alongside.
+ */
+export class GitHubSource {
+    opts;
+    #branch;
+    #cache;
+    #headTtl;
+    #apiBase;
+    constructor(opts) {
+        this.opts = opts;
+        this.#branch = opts.branch;
+        this.#cache = opts.cache ?? sharedMemoryCache();
+        this.#headTtl = opts.headTtl ?? 20;
+        this.#apiBase = (opts.apiBase ?? "https://api.github.com").replace(/\/$/, "");
+    }
+    info() {
+        return {
+            kind: "github",
+            label: `${this.opts.owner}/${this.opts.repo}${this.#branch ? `@${this.#branch}` : ""}`,
+            branch: this.#branch,
+            url: `https://github.com/${this.opts.owner}/${this.opts.repo}`,
+        };
+    }
+    get repoPath() {
+        return `${this.opts.owner}/${this.opts.repo}`;
+    }
+    async #token() {
+        return typeof this.opts.token === "function"
+            ? this.opts.token()
+            : this.opts.token;
+    }
+    async #request(path, init = {}) {
+        const headers = new Headers(init.headers);
+        headers.set("Authorization", `Bearer ${await this.#token()}`);
+        headers.set("Accept", init.raw
+            ? "application/vnd.github.raw+json"
+            : "application/vnd.github+json");
+        headers.set("X-GitHub-Api-Version", "2022-11-28");
+        headers.set("User-Agent", "vestry");
+        if (typeof init.body === "string")
+            headers.set("Content-Type", "application/json");
+        if (init.etag)
+            headers.set("If-None-Match", init.etag);
+        let res = await fetch(`${this.#apiBase}${path}`, { ...init, headers });
+        if (res.status === 401 &&
+            typeof this.opts.token === "function" &&
+            "invalidate" in this.opts.token) {
+            // A cached installation token GitHub no longer accepts (app reinstalled,
+            // key rotated): mint a fresh one and retry once.
+            this.opts.token.invalidate();
+            headers.set("Authorization", `Bearer ${await this.#token()}`);
+            res = await fetch(`${this.#apiBase}${path}`, { ...init, headers });
+        }
+        if (res.status === 304) {
+            return { status: 304, data: undefined, etag: init.etag };
+        }
+        if (!res.ok) {
+            let message = `GitHub API ${res.status} for ${path}`;
+            try {
+                const body = (await res.json());
+                if (body.message)
+                    message = `${body.message} (${res.status} ${path})`;
+            }
+            catch {
+                /* ignore */
+            }
+            const code = res.status === 401
+                ? "unauthorized"
+                : res.status === 403
+                    ? "forbidden"
+                    : res.status === 404
+                        ? "not_found"
+                        : res.status === 409
+                            ? "conflict"
+                            : "github_error";
+            throw new SourceError(message, res.status === 404 ? 404 : res.status, code);
+        }
+        const data = (init.raw ? new Uint8Array(await res.arrayBuffer()) : await res.json());
+        return {
+            status: res.status,
+            data,
+            etag: res.headers.get("etag") ?? undefined,
+        };
+    }
+    async branch() {
+        if (this.#branch)
+            return this.#branch;
+        const key = `gh:${this.repoPath}:default-branch`;
+        const cached = await this.#cache.get(key);
+        if (cached)
+            return (this.#branch = cached);
+        const { data } = await this.#request(`/repos/${this.repoPath}`);
+        this.#branch = data.default_branch;
+        await this.#cache.set(key, this.#branch, 3600);
+        return this.#branch;
+    }
+    #headKey(branch) {
+        return `gh:${this.repoPath}:head:${branch}`;
+    }
+    async #resolveHead() {
+        const branch = await this.branch();
+        const key = this.#headKey(branch);
+        const fresh = await this.#cache.get(key);
+        if (fresh && Date.now() - fresh.checked < this.#headTtl * 1000)
+            return fresh;
+        const { status, data, etag } = await this.#request(`/repos/${this.repoPath}/git/ref/heads/${encodeURIComponent(branch)}`, {
+            etag: fresh?.etag,
+        });
+        if (status === 304 && fresh) {
+            const bumped = { ...fresh, checked: Date.now() };
+            await this.#cache.set(key, bumped, 3600);
+            return bumped;
+        }
+        const sha = data.object.sha;
+        const treeSha = await this.#treeShaForCommit(sha);
+        const head = { sha, treeSha, etag, checked: Date.now() };
+        await this.#cache.set(key, head, 3600);
+        return head;
+    }
+    async #treeShaForCommit(commitSha) {
+        const key = `gh:${this.repoPath}:commit:${commitSha}`;
+        const cached = await this.#cache.get(key);
+        if (cached)
+            return cached;
+        const { data } = await this.#request(`/repos/${this.repoPath}/git/commits/${commitSha}`);
+        await this.#cache.set(key, data.tree.sha);
+        return data.tree.sha;
+    }
+    async head() {
+        return (await this.#resolveHead()).sha;
+    }
+    async #tree(treeSha) {
+        const key = `gh:${this.repoPath}:tree:${treeSha}`;
+        const cached = await this.#cache.get(key);
+        if (cached)
+            return cached;
+        const { data } = await this.#request(`/repos/${this.repoPath}/git/trees/${treeSha}?recursive=1`);
+        if (data.truncated) {
+            throw new SourceError("Repository tree is too large for the GitHub API to return in one request", 500, "tree_truncated");
+        }
+        const entries = data.tree
+            .filter((e) => e.type === "blob")
+            .map((e) => ({ path: e.path, sha: e.sha, size: e.size }));
+        await this.#cache.set(key, entries);
+        return entries;
+    }
+    async list(directory) {
+        const head = await this.#resolveHead();
+        const dir = normalizePath(directory);
+        const all = await this.#tree(head.treeSha);
+        if (!dir)
+            return all;
+        const prefix = `${dir}/`;
+        return all.filter((e) => e.path.startsWith(prefix));
+    }
+    async #findBlob(p) {
+        const head = await this.#resolveHead();
+        const all = await this.#tree(head.treeSha);
+        const n = normalizePath(p);
+        return all.find((e) => e.path === n);
+    }
+    async readBlob(sha) {
+        const key = `gh:${this.repoPath}:blob:${sha}`;
+        const cached = await this.#cache.get(key);
+        if (cached !== undefined)
+            return base64Decode(cached);
+        const { data } = await this.#request(`/repos/${this.repoPath}/git/blobs/${sha}`, { raw: true });
+        // Cache up to ~2 MB blobs; bigger files are re-fetched on demand.
+        if (data.byteLength <= 2 * 1024 * 1024) {
+            await this.#cache.set(key, base64Encode(data));
+        }
+        return data;
+    }
+    async read(p) {
+        if (!isSafeRepoPath(p))
+            throw new SourceError(`Invalid path "${p}"`, 400, "bad_path");
+        const entry = await this.#findBlob(p);
+        if (!entry)
+            return null;
+        return { bytes: await this.readBlob(entry.sha), sha: entry.sha };
+    }
+    async commit(changes, options) {
+        const branch = await this.branch();
+        const head = await this.#resolveHead();
+        if (options.expectedHead && options.expectedHead !== head.sha) {
+            // Someone else pushed; the caller decides whether that's a conflict for
+            // the specific files it touched. We still build on the latest head.
+        }
+        const tree = [];
+        for (const change of changes) {
+            if (!isSafeRepoPath(change.path)) {
+                throw new SourceError(`Invalid path "${change.path}"`, 400, "bad_path");
+            }
+            if ("delete" in change) {
+                tree.push({
+                    path: normalizePath(change.path),
+                    mode: "100644",
+                    type: "blob",
+                    sha: null,
+                });
+                continue;
+            }
+            const bytes = toBytes(change.content);
+            const { data: blob } = await this.#request(`/repos/${this.repoPath}/git/blobs`, {
+                method: "POST",
+                body: JSON.stringify({
+                    content: base64Encode(bytes),
+                    encoding: "base64",
+                }),
+            });
+            await this.#cache.set(`gh:${this.repoPath}:blob:${blob.sha}`, base64Encode(bytes));
+            tree.push({
+                path: normalizePath(change.path),
+                mode: "100644",
+                type: "blob",
+                sha: blob.sha,
+            });
+        }
+        const { data: newTree } = await this.#request(`/repos/${this.repoPath}/git/trees`, {
+            method: "POST",
+            body: JSON.stringify({ base_tree: head.treeSha, tree }),
+        });
+        const { data: commit } = await this.#request(`/repos/${this.repoPath}/git/commits`, {
+            method: "POST",
+            body: JSON.stringify({
+                // Author and committer default to the token's identity (the GitHub
+                // App's bot). Setting `author` would make GitHub copy it into the
+                // committer too, so the editor is credited as a co-author instead.
+                message: withCoAuthor(options.message, options.author),
+                tree: newTree.sha,
+                parents: [head.sha],
+            }),
+        });
+        try {
+            await this.#request(`/repos/${this.repoPath}/git/refs/heads/${encodeURIComponent(branch)}`, {
+                method: "PATCH",
+                body: JSON.stringify({ sha: commit.sha, force: false }),
+            });
+        }
+        catch (e) {
+            if (e instanceof SourceError && (e.status === 422 || e.status === 409)) {
+                // Not a fast-forward: the branch moved while we were committing.
+                await this.#cache.delete(this.#headKey(branch));
+                throw new SourceError("The branch changed while saving. Reload and try again.", 409, "conflict");
+            }
+            throw e;
+        }
+        const newHead = {
+            sha: commit.sha,
+            treeSha: newTree.sha,
+            etag: undefined,
+            checked: Date.now(),
+        };
+        await this.#cache.set(this.#headKey(branch), newHead, 3600);
+        await this.#cache.set(`gh:${this.repoPath}:commit:${commit.sha}`, newTree.sha);
+        return { sha: commit.sha, url: commit.html_url };
+    }
+}
+/** Appends a `Co-authored-by` trailer, which GitHub shows as a second author. */
+function withCoAuthor(message, author) {
+    if (!author?.email)
+        return message;
+    const trailer = `Co-authored-by: ${author.name || author.email} <${author.email}>`;
+    return `${message.trimEnd()}\n\n${trailer}`;
+}

package/dist/core/sources/local.d.ts

@@ -0,0 +1,16 @@
+import { type CommitInfo, type CommitOptions, type ContentSource, type FileChange, type FileData, type SourceInfo, type TreeEntry } from "../source.js";
+/**
+ * Reads and writes the project directory directly. Used by `astro dev` so
+ * editing feels instant and shows up in HMR; the developer commits with git
+ * as usual.
+ */
+export declare class LocalSource implements ContentSource {
+    #private;
+    private root;
+    constructor(root: string);
+    info(): SourceInfo;
+    head(): Promise<string>;
+    list(directory: string): Promise<TreeEntry[]>;
+    read(p: string): Promise<FileData | null>;
+    commit(changes: FileChange[], _options: CommitOptions): Promise<CommitInfo>;
+}

package/dist/core/sources/local.js

@@ -0,0 +1,98 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { gitBlobSha, toBytes, SourceError, } from "../source.js";
+import { isSafeRepoPath, normalizePath } from "../paths.js";
+const IGNORED_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    ".astro",
+    ".wrangler",
+]);
+/**
+ * Reads and writes the project directory directly. Used by `astro dev` so
+ * editing feels instant and shows up in HMR; the developer commits with git
+ * as usual.
+ */
+export class LocalSource {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    info() {
+        return { kind: "local", label: this.root };
+    }
+    async head() {
+        // Not a commit, but stable within a process so the UI can use it as a cache key.
+        return "local";
+    }
+    #abs(p) {
+        const n = normalizePath(p);
+        if (!isSafeRepoPath(n))
+            throw new SourceError(`Invalid path "${p}"`, 400, "bad_path");
+        const abs = path.resolve(this.root, n);
+        if (!abs.startsWith(path.resolve(this.root) + path.sep) &&
+            abs !== path.resolve(this.root)) {
+            throw new SourceError(`Path escapes project root: "${p}"`, 400, "bad_path");
+        }
+        return abs;
+    }
+    async list(directory) {
+        const base = this.#abs(directory);
+        const out = [];
+        const walk = async (dir, rel) => {
+            let entries;
+            try {
+                entries = await fs.readdir(dir, { withFileTypes: true });
+            }
+            catch (e) {
+                if (e.code === "ENOENT")
+                    return;
+                throw e;
+            }
+            for (const entry of entries) {
+                if (IGNORED_DIRS.has(entry.name))
+                    continue;
+                const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    await walk(path.join(dir, entry.name), relPath);
+                }
+                else if (entry.isFile()) {
+                    const abs = path.join(dir, entry.name);
+                    const bytes = await fs.readFile(abs);
+                    out.push({
+                        path: normalizePath(`${directory}/${relPath}`),
+                        sha: await gitBlobSha(new Uint8Array(bytes)),
+                        size: bytes.byteLength,
+                    });
+                }
+            }
+        };
+        await walk(base, "");
+        return out;
+    }
+    async read(p) {
+        try {
+            const buf = await fs.readFile(this.#abs(p));
+            const bytes = new Uint8Array(buf);
+            return { bytes, sha: await gitBlobSha(bytes) };
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return null;
+            throw e;
+        }
+    }
+    async commit(changes, _options) {
+        for (const change of changes) {
+            const abs = this.#abs(change.path);
+            if ("delete" in change) {
+                await fs.rm(abs, { force: true });
+                continue;
+            }
+            await fs.mkdir(path.dirname(abs), { recursive: true });
+            await fs.writeFile(abs, toBytes(change.content));
+        }
+        return { sha: "local" };
+    }
+}

package/dist/core/values.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Value transforms shared by the server and the control panel: asset path
+ * normalisation and automatic fields. Pure functions, no I/O.
+ */
+import type { Field, Schema } from "../config/types.js";
+export declare function walkValues(schema: Schema, data: Record<string, unknown>, fn: (field: Field, value: unknown) => unknown): Record<string, unknown>;
+export type AssetField = Extract<Field, {
+    type: "image" | "file";
+}>;
+export type AssetLike = {
+    directory: string;
+    storeAs?: AssetField["storeAs"];
+};
+export declare function defaultStorage(field: AssetLike): NonNullable<AssetField["storeAs"]>;
+/** Stored reference (relative path, bare filename, public URL) → repository path. */
+export declare function assetToRepoPath(field: AssetLike, value: string, filePath: string): string;
+/** Repository path → the reference written into the content file. */
+export declare function repoPathToAsset(field: AssetLike, repoPath: string, filePath: string): string;
+/** Convert stored values to the editor's canonical representation (repo paths, ISO strings). */
+export declare function toEditorValues(schema: Schema, data: Record<string, unknown>, filePath: string): Record<string, unknown>;
+export declare function toStoredValues(schema: Schema, data: Record<string, unknown>, filePath: string): Record<string, unknown>;
+export declare function applyAutoFields(schema: Schema, data: Record<string, unknown>, now?: Date): Record<string, unknown>;