@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/apps/github.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The app's own builds: files of a release of the app's own GitHub repository (campaign
+ * 2026-10-20, FM4). Only `https://github.com/<owner>/<name>/releases/download/<tag>/<file>` of
+ * exactly that repository is accepted. A private repository is read with the company's GitHub
+ * token through the API's asset endpoint; the token is sent to api.github.com only, never to the
+ * download it redirects to, and never reaches an error.
+ */
+export interface ReleaseAsset {
+    owner: string;
+    name: string;
+    tag: string;
+    file: string;
+}
+/** `owner/name` with GitHub's own name rules, or `null`. `.` and `..` are not names. */
+export declare function parseAppRepo(repo: unknown): {
+    owner: string;
+    name: string;
+} | null;
+/**
+ * The release asset `url` names when it is a file of a release of `repo` (owner and name compared
+ * as GitHub does, ignoring case), else `null`.
+ */
+export declare function releaseAssetOf(url: unknown, repo: string): ReleaseAsset | null;
+/** A failed read: `code` says why (kept by `withCallTimeout`), `status` when GitHub answered; never the token or a body. */
+export declare class ReleaseAssetError extends Error {
+    readonly code: 'not_found' | 'refused' | 'too_large' | 'failed';
+    readonly status?: number | undefined;
+    constructor(code: 'not_found' | 'refused' | 'too_large' | 'failed', status?: number | undefined);
+}
+/**
+ * Where a download may be sent: GitHub's own release storage. GitHub has served release files
+ * from `objects.githubusercontent.com`, `github-releases.githubusercontent.com` and (since 2025)
+ * `release-assets.githubusercontent.com`; all are `*.githubusercontent.com`, which only GitHub
+ * serves. Any other host is refused, so a redirect cannot point the read anywhere else.
+ */
+export declare const isReleaseDownloadHost: (host: string) => boolean;
+/**
+ * Downloads `asset`. With `token`: the release by tag, the asset by name, then its bytes through
+ * the asset endpoint (`Accept: application/octet-stream`); the redirect GitHub answers with is
+ * followed without the token. Without: the public download URL.
+ */
+export declare function fetchReleaseAsset(asset: ReleaseAsset, opts: {
+    token?: string | null;
+    fetch: typeof fetch;
+    timeoutMs: number;
+    maxBytes: number;
+}): Promise<Uint8Array>;

package/dist/apps/github.js

@@ -0,0 +1,201 @@
+/**
+ * The app's own builds: files of a release of the app's own GitHub repository (campaign
+ * 2026-10-20, FM4). Only `https://github.com/<owner>/<name>/releases/download/<tag>/<file>` of
+ * exactly that repository is accepted. A private repository is read with the company's GitHub
+ * token through the API's asset endpoint; the token is sent to api.github.com only, never to the
+ * download it redirects to, and never reaches an error.
+ */
+const REPO = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]{1,100})$/;
+const RELEASE_ASSET = /^https:\/\/github\.com\/([A-Za-z0-9-]{1,39})\/([A-Za-z0-9._-]{1,100})\/releases\/download\/([^/?#\s]{1,200})\/([^/?#\s]{1,200})$/;
+const GITHUB_API = 'https://api.github.com';
+const TOKEN = /^[\x21-\x7e]{1,512}$/;
+/** `owner/name` with GitHub's own name rules, or `null`. `.` and `..` are not names. */
+export function parseAppRepo(repo) {
+    if (typeof repo !== 'string')
+        return null;
+    const match = REPO.exec(repo);
+    if (!match?.[1] || !match[2] || /^\.+$/.test(match[2]))
+        return null;
+    return { owner: match[1], name: match[2] };
+}
+/**
+ * The release asset `url` names when it is a file of a release of `repo` (owner and name compared
+ * as GitHub does, ignoring case), else `null`.
+ */
+export function releaseAssetOf(url, repo) {
+    const own = parseAppRepo(repo);
+    if (!own || typeof url !== 'string')
+        return null;
+    const match = RELEASE_ASSET.exec(url);
+    if (!match)
+        return null;
+    const [, owner = '', name = '', rawTag = '', rawFile = ''] = match;
+    if (owner.toLowerCase() !== own.owner.toLowerCase())
+        return null;
+    if (name.toLowerCase() !== own.name.toLowerCase())
+        return null;
+    let tag;
+    let file;
+    try {
+        tag = decodeURIComponent(rawTag);
+        file = decodeURIComponent(rawFile);
+    }
+    catch {
+        return null;
+    }
+    if ([tag, file].some((part) => /^\.+$/.test(part) || /[/\\\s]/.test(part) || part === '')) {
+        return null;
+    }
+    return { owner, name, tag, file };
+}
+/** A failed read: `code` says why (kept by `withCallTimeout`), `status` when GitHub answered; never the token or a body. */
+export class ReleaseAssetError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(`release asset ${code}${status ? ` (${status})` : ''}`);
+        this.code = code;
+        this.status = status;
+        this.name = 'ReleaseAssetError';
+    }
+}
+/** The release's JSON (one entry per asset): far below this even for a release with hundreds. */
+const RELEASE_JSON_MAX_BYTES = 2 * 1024 * 1024;
+const REDIRECTS_MAX = 5;
+/**
+ * Where a download may be sent: GitHub's own release storage. GitHub has served release files
+ * from `objects.githubusercontent.com`, `github-releases.githubusercontent.com` and (since 2025)
+ * `release-assets.githubusercontent.com`; all are `*.githubusercontent.com`, which only GitHub
+ * serves. Any other host is refused, so a redirect cannot point the read anywhere else.
+ */
+export const isReleaseDownloadHost = (host) => host === 'github.com' || /^[a-z0-9-]+(\.[a-z0-9-]+)*\.githubusercontent\.com$/.test(host);
+/**
+ * The body, at most `maxBytes`, read as it streams: a missing or false content-length cannot make
+ * it read more. `deadline` bounds the read even when the fetch ignores its signal.
+ */
+async function readCapped(response, maxBytes, deadline) {
+    const length = Number(response.headers.get('content-length') ?? '');
+    if (Number.isFinite(length) && length > maxBytes) {
+        await response.body?.cancel().catch(() => { });
+        throw new ReleaseAssetError('too_large');
+    }
+    const body = response.body;
+    if (!body)
+        return new Uint8Array(0);
+    const reader = body.getReader();
+    const parts = [];
+    let size = 0;
+    const timedOut = new Promise((_, reject) => {
+        if (deadline.aborted)
+            reject(new ReleaseAssetError('failed'));
+        deadline.addEventListener('abort', () => reject(new ReleaseAssetError('failed')), {
+            once: true,
+        });
+    });
+    timedOut.catch(() => { });
+    try {
+        for (;;) {
+            const { done, value } = await Promise.race([reader.read(), timedOut]);
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > maxBytes)
+                throw new ReleaseAssetError('too_large');
+            parts.push(value);
+        }
+    }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        throw error;
+    }
+    const bytes = new Uint8Array(size);
+    let at = 0;
+    for (const part of parts) {
+        bytes.set(part, at);
+        at += part.byteLength;
+    }
+    return bytes;
+}
+const failure = (status) => new ReleaseAssetError(status === 404 ? 'not_found' : status === 401 || status === 403 ? 'refused' : 'failed', status);
+/**
+ * Downloads `asset`. With `token`: the release by tag, the asset by name, then its bytes through
+ * the asset endpoint (`Accept: application/octet-stream`); the redirect GitHub answers with is
+ * followed without the token. Without: the public download URL.
+ */
+export async function fetchReleaseAsset(asset, opts) {
+    // Each request (and the read of its body) has its own deadline.
+    const deadline = () => AbortSignal.timeout(opts.timeoutMs);
+    const path = `${encodeURIComponent(asset.owner)}/${encodeURIComponent(asset.name)}`;
+    /** Follows redirects by hand, without the token, to GitHub's release storage only. */
+    const download = async (start) => {
+        let url = start;
+        for (let hop = 0; hop <= REDIRECTS_MAX; hop++) {
+            let target;
+            try {
+                target = new URL(url);
+            }
+            catch {
+                throw new ReleaseAssetError('failed');
+            }
+            if (target.protocol !== 'https:' || !isReleaseDownloadHost(target.hostname)) {
+                throw new ReleaseAssetError('failed');
+            }
+            const signal = deadline();
+            const response = await opts.fetch(target.toString(), { redirect: 'manual', signal });
+            if (response.status >= 300 && response.status < 400) {
+                await response.body?.cancel().catch(() => { });
+                url = new URL(response.headers.get('location') ?? '', target).toString();
+                continue;
+            }
+            if (!response.ok)
+                throw failure(response.status);
+            return readCapped(response, opts.maxBytes, signal);
+        }
+        throw new ReleaseAssetError('failed');
+    };
+    if (!opts.token) {
+        return download(`https://github.com/${path}/releases/download/${encodeURIComponent(asset.tag)}/${encodeURIComponent(asset.file)}`);
+    }
+    if (!TOKEN.test(opts.token))
+        throw new ReleaseAssetError('refused');
+    const headers = {
+        Authorization: `Bearer ${opts.token}`,
+        'X-GitHub-Api-Version': '2022-11-28',
+        'User-Agent': 'wtfalch-foundry',
+    };
+    const releaseSignal = deadline();
+    const release = await opts.fetch(`${GITHUB_API}/repos/${path}/releases/tags/${encodeURIComponent(asset.tag)}`, { headers: { ...headers, Accept: 'application/vnd.github+json' }, signal: releaseSignal });
+    if (!release.ok)
+        throw failure(release.status);
+    let body = null;
+    try {
+        body = JSON.parse(new TextDecoder().decode(await readCapped(release, RELEASE_JSON_MAX_BYTES, releaseSignal)));
+    }
+    catch (error) {
+        if (error instanceof ReleaseAssetError && error.code === 'too_large') {
+            throw new ReleaseAssetError('failed', release.status);
+        }
+        body = null;
+    }
+    const found = (Array.isArray(body?.assets) ? body.assets : []).find((a) => a?.name === asset.file);
+    if (!found || typeof found.id !== 'number' || !Number.isSafeInteger(found.id)) {
+        throw new ReleaseAssetError('not_found');
+    }
+    if (typeof found.size === 'number' && found.size > opts.maxBytes) {
+        throw new ReleaseAssetError('too_large');
+    }
+    const answerSignal = deadline();
+    const answer = await opts.fetch(`${GITHUB_API}/repos/${path}/releases/assets/${found.id}`, {
+        headers: { ...headers, Accept: 'application/octet-stream' },
+        redirect: 'manual',
+        signal: answerSignal,
+    });
+    if (answer.status >= 300 && answer.status < 400) {
+        await answer.body?.cancel().catch(() => { });
+        // The signed download needs no token, and must never see it.
+        return download(answer.headers.get('location') ?? '');
+    }
+    if (!answer.ok)
+        throw failure(answer.status);
+    return readCapped(answer, opts.maxBytes, answerSignal);
+}

package/dist/apps/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@wtfalch/foundry/apps`: one Worker app into a company's own Cloudflare account. Boule calls
+ * these in-process with the company's own token (campaign 2026-10-20, FM3).
+ */
+export { type AppCopy, type AppsDeps, type AppsFailure, type AppsResult, type DeployWorkerAppInput, type RemoveWorkerAppInput, appHyperdriveName, appScriptName, deployWorkerApp, mcpMachinePaths, removeWorkerApp, } from './deploy.js';
+export { type ApplyWorkerAppMigrationsDeps, type ApplyWorkerAppMigrationsInput, type DatabaseOwnerAddress, type MigrationsResult, type MigrationsStep, RELEASE_MIGRATION_SOURCE, type RuntimeRoleOrigin, type RuntimeRolePrivileges, type WorkerAppDatabaseRunner, applyWorkerAppMigrations, migrationChecksum, postgresMigrationRunner, runtimeRoleMarker, } from './migrations.js';
+export { type ReleaseAsset, ReleaseAssetError, fetchReleaseAsset, parseAppRepo, releaseAssetOf, } from './github.js';
+export { type WorkerAppMigrationRunner, migrationsUrl } from '../worker-app-migrations.js';
+export { APPS_CLOUDFLARE_TOKEN_PERMISSIONS, type AppsCloudflare, type HyperdriveConnection, } from './cloudflare.js';

package/dist/apps/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@wtfalch/foundry/apps`: one Worker app into a company's own Cloudflare account. Boule calls
+ * these in-process with the company's own token (campaign 2026-10-20, FM3).
+ */
+export { appHyperdriveName, appScriptName, deployWorkerApp, mcpMachinePaths, removeWorkerApp, } from './deploy.js';
+export { RELEASE_MIGRATION_SOURCE, applyWorkerAppMigrations, migrationChecksum, postgresMigrationRunner, runtimeRoleMarker, } from './migrations.js';
+export { ReleaseAssetError, fetchReleaseAsset, parseAppRepo, releaseAssetOf, } from './github.js';
+export { migrationsUrl } from '../worker-app-migrations.js';
+export { APPS_CLOUDFLARE_TOKEN_PERMISSIONS, } from './cloudflare.js';

package/dist/apps/migrations.d.ts

@@ -0,0 +1,110 @@
+import { type WorkerAppMigrationRunner } from '../worker-app-migrations.js';
+/**
+ * The build's database changes (`migrations.json`) into the company's own Postgres (campaign
+ * 2026-10-20, FM4). Boule calls it before `deployWorkerApp`, with the owner address of the
+ * company's database and the address the app's runtime role uses (the one Boule then hands
+ * `deployWorkerApp` as `database.url`). The same steps as the platform's Worker app database
+ * (`runWorkerAppMigrations`): the file's sha256 is checked against build.json's
+ * `migrationsSha256`, only the migrations the database's ledger lacks run, in order, as the owner,
+ * then the runtime role gets DML on the tables, loses UPDATE, DELETE and TRUNCATE on the
+ * append-only ones and gets EXECUTE on the granted functions.
+ *
+ * The ledger is `_migrations_sources`, source `release`, the one `@wtfalch/db`'s runner writes
+ * and the platform's host reads, so a database moved between the two keeps its history.
+ *
+ * Before anything runs, a runtime role that already exists must be one this function made for
+ * this database (its comment says so), and every migration the ledger holds must still have the
+ * text it ran with (the ledger's checksum). After the role work, the role is read back: each
+ * append-only table must exist and the role must hold no UPDATE, DELETE or TRUNCATE on it, also
+ * not through PUBLIC or a role it belongs to, and it must hold EXECUTE on each granted function.
+ *
+ * A call that does not answer in time is cancelled on the server. A change that was running then
+ * may or may not have finished; the ledger and the runner's lock make a rerun safe either way,
+ * except for a change marked `-- db:no-transaction`, which may have kept part of itself.
+ *
+ * Never throws. A failure is `{ ok: false, step, message }` in plain words; no message holds
+ * an address, a password, SQL or anything the database answered beyond its SQLSTATE.
+ */
+export interface ApplyWorkerAppMigrationsInput {
+    /** Owns the schema: the migrations run as this role. */
+    ownerUrl: string;
+    /** The role the app runs as (through Hyperdrive). It is created, or its password updated, from this address. */
+    runtimeUrl: string;
+    /** The release's `migrations.json`, or `null` when the release has none. */
+    migrationsJson: string | null;
+    /** build.json's `database.migrationsSha256`. Required when `migrationsJson` is given. */
+    migrationsSha256?: string | undefined;
+    /** build.json's `database.appendOnly`. */
+    appendOnly?: string[] | undefined;
+    /** build.json's `database.grants`. */
+    grants?: string[] | undefined;
+}
+/** The owner as the runner sees it. */
+export interface DatabaseOwnerAddress {
+    url: string;
+}
+/** What the runtime role may do on what build.json names, read back after the role work. */
+export interface RuntimeRolePrivileges {
+    tables: {
+        name: string;
+        exists: boolean;
+        update: boolean;
+        delete: boolean;
+        truncate: boolean;
+    }[];
+    functions: {
+        signature: string;
+        exists: boolean;
+        execute: boolean;
+    }[];
+}
+/** Who made the runtime role: none yet, this function for this database, or someone else. */
+export type RuntimeRoleOrigin = 'absent' | 'ours' | 'other';
+/** The shared runner, plus what the company-Postgres path checks before and after it. */
+export interface WorkerAppDatabaseRunner extends WorkerAppMigrationRunner<DatabaseOwnerAddress> {
+    /** The ledger's checksum of each applied migration (`null` when the ledger has none for it). */
+    appliedChecksums(owner: DatabaseOwnerAddress): Promise<Record<string, string | null>>;
+    /** Whether `user` exists, and if so whether this function made it for this database. */
+    runtimeRoleOrigin(owner: DatabaseOwnerAddress, user: string): Promise<RuntimeRoleOrigin>;
+    /** After `ensureRuntimeRole`: the role's rights on the named tables and functions. */
+    runtimeRolePrivileges(owner: DatabaseOwnerAddress, input: {
+        user: string;
+        appendOnly: string[];
+        grants: string[];
+    }): Promise<RuntimeRolePrivileges>;
+    /** Closes every connection the runner has open now, without waiting for the work on it. */
+    abort(): Promise<void>;
+}
+export interface ApplyWorkerAppMigrationsDeps {
+    /** The SQL runner. Default: `@wtfalch/db`'s migrate and runtime-role (`postgresMigrationRunner`). */
+    sql?: WorkerAppDatabaseRunner;
+    /** Test hooks: the timeout of the ledger read and the role work, and of one migration. */
+    timeoutMs?: number;
+    migrationTimeoutMs?: number;
+}
+export type MigrationsStep = 'check' | 'database' | 'migrations' | 'role';
+export type MigrationsResult = {
+    ok: true;
+    applied: string[];
+    ran: string[];
+    steps: string[];
+} | {
+    ok: false;
+    step: MigrationsStep;
+    message: string;
+    ran: string[];
+    steps: string[];
+};
+/** The ledger source the release's migrations are recorded under. */
+export declare const RELEASE_MIGRATION_SOURCE = "release";
+/** The comment a runtime role this function made carries: it names the database it was made for. */
+export declare const runtimeRoleMarker: (database: string) => string;
+/** The ledger's checksum of a migration's text, as `@wtfalch/db` writes it (CRLF read as LF). */
+export declare const migrationChecksum: (sql: string) => string;
+/**
+ * Runs the release's database changes into the company's Postgres and makes the app's role
+ * true. Rerunning is safe: applied migrations are skipped by the ledger.
+ */
+export declare function applyWorkerAppMigrations(input: ApplyWorkerAppMigrationsInput, deps?: ApplyWorkerAppMigrationsDeps): Promise<MigrationsResult>;
+/** The default runner, on `@wtfalch/db` (loaded on first use, so only a caller of it needs the package). */
+export declare function postgresMigrationRunner(): WorkerAppDatabaseRunner;