@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/dist/modules/github-app/github-app.connection.d.ts

@@ -0,0 +1,102 @@
+import type { GitHubAppRepository, SettingReader } from '../settings/repository-source.js';
+import { GitHubAppClient, type GitHubAppCredentials, type InstallationRepository } from './github-app.client.js';
+/** The repositories a person may connect, as a setting holds them: one `owner/name` a line. */
+export declare function repositoriesAsSetting(names: string[]): string;
+export interface GitHubAppConnectionOptions {
+    /** The deployment's settings, as they are in effect. */
+    read: SettingReader;
+    /** Where a setting's value comes from: what tells an app the operator supplied from one setup registered. */
+    sourceOf(key: string): 'env' | 'stored' | 'unset';
+    client?: GitHubAppClient;
+    now?: () => number;
+}
+/**
+ * The deployment's connection to GitHub through a GitHub App: the app it
+ * acts as, the installation it was given, the repositories it may be
+ * pointed at, and the token that stands for the first two when git runs.
+ *
+ * THE TOKEN EXPIRES. An installation token is good for an hour, which is
+ * the point of it: nothing long-lived is stored that reaches the
+ * repository. It is kept in memory, renewed before it runs out, and never
+ * written anywhere. A deployment that restarts asks for a new one.
+ *
+ * What is stored is what cannot be asked for again: the app's private key,
+ * encrypted like every secret, the number of the installation, and the
+ * repositories the person who connected it could push to.
+ *
+ * WHAT THE INSTALLATION REACHES IS NOT WHAT THE DEPLOYMENT MAY USE. An
+ * installation's token reads and writes every repository the installation
+ * covers. The person who connected it may hold far less: being able to
+ * read ONE of those repositories is enough for GitHub to count the
+ * installation among theirs. So the deployment is limited to what that
+ * person could push to with their own account, recorded when they
+ * connected (see {@link permits}); the installation's reach is what git
+ * works through, never what is offered.
+ */
+export declare class GitHubAppConnection implements GitHubAppRepository {
+    private readonly opts;
+    private readonly client;
+    private readonly now;
+    private readonly log;
+    /** The token in hand and what it is a token FOR: another app or installation is another token. */
+    private held;
+    /** One renewal at a time, shared by every git call that arrives during it. */
+    private renewing;
+    /** The last renewal failed: how many in a row have, and until when GitHub is not asked again. */
+    private failed;
+    constructor(opts: GitHubAppConnectionOptions);
+    /** The app the deployment acts as, or null while any part of it is missing. */
+    credentials(read?: SettingReader): GitHubAppCredentials | null;
+    /** Who supplied the app: whoever operates the deployment, or the setup screen. Null: there is none. */
+    registeredBy(): 'environment' | 'setup' | null;
+    installationId(read?: SettingReader): string;
+    url(read?: SettingReader): string;
+    answered(read?: SettingReader): boolean;
+    /**
+     * Whether the deployment may be pointed at `repository`: it is one the
+     * person who connected the installation could push to.
+     *
+     * An installation the OPERATOR supplied, through the environment, has no
+     * such person. It is the operator's statement about their own
+     * deployment, and everything it reaches is permitted, as everything an
+     * access token reaches is.
+     */
+    permits(repository: string, read?: SettingReader): boolean;
+    token(): string | null;
+    /**
+     * Have a token for the call about to be made, WITHOUT MAKING THE CALL
+     * WAIT ON GITHUB UNLESS IT HAS TO. This runs before every git call the
+     * deployment makes, the ones that never leave the disk included.
+     *
+     *  - A token with time to spare: nothing is asked.
+     *  - A token that is good but close to running out: a renewal is started
+     *    and the call goes ahead with the token in hand.
+     *  - No token that is good: the call waits for one, and gets what GitHub
+     *    says, unless GitHub has just failed to give one. A failure is
+     *    remembered for a short while that grows with each one in a row, and
+     *    inside it nothing is asked: git runs with no token, and a call that
+     *    needed one is told so by the host, at once.
+     *
+     * `asked` is for an admin waiting on the answer itself (the setup screen
+     * listing repositories, proving a connection): GitHub is asked whatever
+     * is remembered, and the failure is thrown.
+     */
+    prepare(opts?: {
+        asked?: boolean;
+    }): Promise<void>;
+    /**
+     * The repositories the deployment may be pointed at: those the
+     * installation reaches AND the person who connected it could push to.
+     * Asked of GitHub each time, so a repository taken out of the
+     * installation since is not offered.
+     */
+    repositories(): Promise<{
+        repositories: InstallationRepository[];
+        more: boolean;
+    }>;
+    /** Drop the token in hand: the installation it was for is no longer the deployment's. */
+    forget(): void;
+    private renew;
+    private holder;
+}
+//# sourceMappingURL=github-app.connection.d.ts.map

package/dist/modules/github-app/github-app.connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app.connection.d.ts","sourceRoot":"","sources":["../../../src/modules/github-app/github-app.connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAC3F,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAQhC,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAE7D;AAED,MAAM,WAAW,0BAA0B;IACzC,wDAAwD;IACxD,IAAI,EAAE,aAAa,CAAC;IACpB,6GAA6G;IAC7G,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IAClD,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,mBAAoB,YAAW,mBAAmB;IAWjD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAVjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA8B;IAClD,kGAAkG;IAClG,OAAO,CAAC,IAAI,CAAkE;IAC9E,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAA8B;IAC9C,iGAAiG;IACjG,OAAO,CAAC,MAAM,CAAiD;gBAElC,IAAI,EAAE,0BAA0B;IAK7D,+EAA+E;IAC/E,WAAW,CAAC,IAAI,GAAE,aAA8B,GAAG,oBAAoB,GAAG,IAAI;IAW9E,uGAAuG;IACvG,YAAY,IAAI,aAAa,GAAG,OAAO,GAAG,IAAI;IAK9C,cAAc,CAAC,IAAI,GAAE,aAA8B,GAAG,MAAM;IAI5D,GAAG,CAAC,IAAI,GAAE,aAA8B,GAAG,MAAM;IAKjD,QAAQ,CAAC,IAAI,GAAE,aAA8B,GAAG,OAAO;IAIvD;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,aAA8B,GAAG,OAAO;IAU1E,KAAK,IAAI,MAAM,GAAG,IAAI;IAMtB;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB5D;;;;;OAKG;IACG,YAAY,IAAI,OAAO,CAAC;QAAE,YAAY,EAAE,sBAAsB,EAAE,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IAQxF,yFAAyF;IACzF,MAAM,IAAI,IAAI;YAKA,KAAK;IAmBnB,OAAO,CAAC,MAAM;CAGf"}

package/dist/modules/github-app/github-app.connection.js

@@ -0,0 +1,185 @@
+import { logger } from '../../shared/logging.js';
+import { GitHubAppClient, } from './github-app.client.js';
+/** Renewed this long before it would expire, so no git call starts on a token with minutes to live. */
+const RENEW_AHEAD_MS = 10 * 60_000;
+/** How long a failed renewal is remembered the first time, and the most it grows to. */
+const FIRST_WAIT_MS = 5_000;
+const LONGEST_WAIT_MS = 5 * 60_000;
+/** The repositories a person may connect, as a setting holds them: one `owner/name` a line. */
+export function repositoriesAsSetting(names) {
+    return [...new Set(names.map((name) => name.trim()).filter(Boolean))].join('\n');
+}
+/**
+ * The deployment's connection to GitHub through a GitHub App: the app it
+ * acts as, the installation it was given, the repositories it may be
+ * pointed at, and the token that stands for the first two when git runs.
+ *
+ * THE TOKEN EXPIRES. An installation token is good for an hour, which is
+ * the point of it: nothing long-lived is stored that reaches the
+ * repository. It is kept in memory, renewed before it runs out, and never
+ * written anywhere. A deployment that restarts asks for a new one.
+ *
+ * What is stored is what cannot be asked for again: the app's private key,
+ * encrypted like every secret, the number of the installation, and the
+ * repositories the person who connected it could push to.
+ *
+ * WHAT THE INSTALLATION REACHES IS NOT WHAT THE DEPLOYMENT MAY USE. An
+ * installation's token reads and writes every repository the installation
+ * covers. The person who connected it may hold far less: being able to
+ * read ONE of those repositories is enough for GitHub to count the
+ * installation among theirs. So the deployment is limited to what that
+ * person could push to with their own account, recorded when they
+ * connected (see {@link permits}); the installation's reach is what git
+ * works through, never what is offered.
+ */
+export class GitHubAppConnection {
+    opts;
+    client;
+    now;
+    log = () => logger('github-app');
+    /** The token in hand and what it is a token FOR: another app or installation is another token. */
+    held = null;
+    /** One renewal at a time, shared by every git call that arrives during it. */
+    renewing = null;
+    /** The last renewal failed: how many in a row have, and until when GitHub is not asked again. */
+    failed = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.client = opts.client ?? new GitHubAppClient();
+        this.now = opts.now ?? Date.now;
+    }
+    /** The app the deployment acts as, or null while any part of it is missing. */
+    credentials(read = this.opts.read) {
+        const credentials = {
+            appId: read('githubAppId'),
+            slug: read('githubAppSlug'),
+            privateKey: read('githubAppPrivateKey'),
+            clientId: read('githubAppClientId'),
+            clientSecret: read('githubAppClientSecret'),
+        };
+        return Object.values(credentials).every(Boolean) ? credentials : null;
+    }
+    /** Who supplied the app: whoever operates the deployment, or the setup screen. Null: there is none. */
+    registeredBy() {
+        if (!this.credentials())
+            return null;
+        return this.opts.sourceOf('githubAppId') === 'env' ? 'environment' : 'setup';
+    }
+    installationId(read = this.opts.read) {
+        return read('githubInstallationId');
+    }
+    url(read = this.opts.read) {
+        const repository = read('githubRepository');
+        return repository ? `https://github.com/${repository}.git` : '';
+    }
+    answered(read = this.opts.read) {
+        return Boolean(this.credentials(read) && this.installationId(read) && read('githubRepository'));
+    }
+    /**
+     * Whether the deployment may be pointed at `repository`: it is one the
+     * person who connected the installation could push to.
+     *
+     * An installation the OPERATOR supplied, through the environment, has no
+     * such person. It is the operator's statement about their own
+     * deployment, and everything it reaches is permitted, as everything an
+     * access token reaches is.
+     */
+    permits(repository, read = this.opts.read) {
+        if (this.opts.sourceOf('githubInstallationId') === 'env')
+            return true;
+        const wanted = repository.trim().toLowerCase();
+        if (!wanted)
+            return false;
+        // GitHub's names do not tell case apart.
+        return read('githubRepositoriesPermitted')
+            .split('\n')
+            .some((name) => name.trim().toLowerCase() === wanted);
+    }
+    token() {
+        const held = this.held;
+        if (!held || held.for !== this.holder() || held.expiresAt <= this.now())
+            return null;
+        return held.token;
+    }
+    /**
+     * Have a token for the call about to be made, WITHOUT MAKING THE CALL
+     * WAIT ON GITHUB UNLESS IT HAS TO. This runs before every git call the
+     * deployment makes, the ones that never leave the disk included.
+     *
+     *  - A token with time to spare: nothing is asked.
+     *  - A token that is good but close to running out: a renewal is started
+     *    and the call goes ahead with the token in hand.
+     *  - No token that is good: the call waits for one, and gets what GitHub
+     *    says, unless GitHub has just failed to give one. A failure is
+     *    remembered for a short while that grows with each one in a row, and
+     *    inside it nothing is asked: git runs with no token, and a call that
+     *    needed one is told so by the host, at once.
+     *
+     * `asked` is for an admin waiting on the answer itself (the setup screen
+     * listing repositories, proving a connection): GitHub is asked whatever
+     * is remembered, and the failure is thrown.
+     */
+    async prepare(opts = {}) {
+        const credentials = this.credentials();
+        const installationId = this.installationId();
+        if (!credentials || !installationId)
+            return;
+        const held = this.held?.for === this.holder() ? this.held : null;
+        const good = held !== null && held.expiresAt > this.now();
+        if (good && held.expiresAt - this.now() > RENEW_AHEAD_MS)
+            return;
+        if (!opts.asked && this.failed && this.now() < this.failed.until)
+            return;
+        this.renewing ??= this.renew(credentials, installationId).finally(() => {
+            this.renewing = null;
+        });
+        if (good && !opts.asked) {
+            // Not waited on, so not thrown to anyone: the renewal has logged it.
+            this.renewing.catch(() => undefined);
+            return;
+        }
+        await this.renewing;
+    }
+    /**
+     * The repositories the deployment may be pointed at: those the
+     * installation reaches AND the person who connected it could push to.
+     * Asked of GitHub each time, so a repository taken out of the
+     * installation since is not offered.
+     */
+    async repositories() {
+        await this.prepare({ asked: true });
+        const token = this.token();
+        if (!token)
+            return { repositories: [], more: false };
+        const reached = await this.client.repositories(token);
+        return { repositories: reached.repositories.filter((r) => this.permits(r.fullName)), more: reached.more };
+    }
+    /** Drop the token in hand: the installation it was for is no longer the deployment's. */
+    forget() {
+        this.held = null;
+        this.failed = null;
+    }
+    async renew(credentials, installationId) {
+        const holder = this.holder();
+        try {
+            const issued = await this.client.installationToken(credentials, installationId);
+            this.held = { for: holder, token: issued.token, expiresAt: issued.expiresAt };
+            this.failed = null;
+        }
+        catch (err) {
+            const times = (this.failed?.times ?? 0) + 1;
+            const wait = Math.min(FIRST_WAIT_MS * 2 ** (times - 1), LONGEST_WAIT_MS);
+            this.failed = { times, until: this.now() + wait };
+            // Once per failure, and a failure is once per wait.
+            this.log().error(`GitHub gave no token for the installation; not asked again for ${Math.round(wait / 1000)} s:`, {
+                detail: err instanceof Error ? err.message : String(err),
+                failuresInARow: times,
+            });
+            throw err;
+        }
+    }
+    holder() {
+        return `${this.opts.read('githubAppId')}:${this.installationId()}`;
+    }
+}
+//# sourceMappingURL=github-app.connection.js.map

package/dist/modules/github-app/github-app.connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app.connection.js","sourceRoot":"","sources":["../../../src/modules/github-app/github-app.connection.ts"],"names":[],"mappings":"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"}

package/dist/modules/github-app/github-app.routes.d.ts

@@ -0,0 +1,59 @@
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { DeploymentSettingsService } from '../settings/deployment-settings.service.js';
+import { GitHubAppClient } from './github-app.client.js';
+import { type GitHubAppConnection } from './github-app.connection.js';
+import '../auth/auth.middleware.js';
+export interface GitHubAppRoutesDeps {
+    settings: Pick<DeploymentSettingsService, 'resolve' | 'record'>;
+    connection: GitHubAppConnection;
+    adminAccess: IAdminAccessService;
+    /** Where GitHub sends the browser back to: this deployment's own address. */
+    publicBackendUrl: string;
+    publicFrontendUrl: string;
+    /** Whether the deployment is set up: decides which page a round trip ends on. */
+    isComplete(): boolean;
+    client?: GitHubAppClient;
+}
+/** The address GitHub is told to send the browser back to once the app is installed. */
+export declare function githubAppCallbackUrl(publicBackendUrl: string): string;
+/**
+ * The manifest a deployment's own GitHub App is created from. It asks for
+ * what the deployment does and nothing else: read and write the contents of
+ * the repositories it is installed on. No webhook, no events, not public:
+ * the app is this deployment's, installed by its owner on the one
+ * repository the knowledge base lives in.
+ */
+export declare function githubAppManifest(publicBackendUrl: string, publicFrontendUrl: string): Record<string, unknown>;
+/**
+ * Connecting a repository on GitHub through a GitHub App, from the setup
+ * screen. Mounted behind the deployment's sign-in; every route is an
+ * admin's.
+ *
+ *   GET  /setup/github-app               where the connection stands
+ *   POST /setup/github-app/manifest      start registering this deployment's own app
+ *   GET  /setup/github-app/registered    GitHub sends the browser back: the app exists
+ *   POST /setup/github-app/install       where on GitHub the app is installed
+ *   POST /setup/github-app/refresh       where to sign in, to read again what may be connected
+ *   GET  /setup/github-app/callback      GitHub sends the browser back: the app is installed
+ *   GET  /setup/github-app/repositories  what the deployment may be pointed at
+ *
+ * A ROUND TRIP IS STARTED BY A POST AND ENDED BY A GET. The two routes
+ * GitHub sends the browser to are ordinary navigations, authenticated by
+ * the session cookie; each checks a state this browser was given when the
+ * round trip started, and spends it. Nothing that starts one is a link, so
+ * a link somebody was sent starts nothing.
+ *
+ * WHAT THE DEPLOYMENT MAY REACH is never taken from the address the browser
+ * came back on. GitHub puts an installation's number there and anyone can
+ * write another: with one app serving many deployments, that number is the
+ * only thing between a deployment and another organisation's repositories.
+ * GitHub sends the person back signed in, and the deployment asks GitHub
+ * two things about THAT PERSON: which installations they reach, and which
+ * repositories of the one they named they can push to with their own
+ * account. The first alone is not enough, since read access to one
+ * repository puts an installation on that list. Only the second is what
+ * the deployment may be pointed at.
+ */
+export declare function createGitHubAppRoutes(deps: GitHubAppRoutesDeps): express.Router;
+//# sourceMappingURL=github-app.routes.d.ts.map

package/dist/modules/github-app/github-app.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/github-app/github-app.routes.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAkB,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAyB,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC7F,OAAO,4BAA4B,CAAC;AAWpC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,IAAI,CAAC,yBAAyB,EAAE,SAAS,GAAG,QAAQ,CAAC,CAAC;IAChE,UAAU,EAAE,mBAAmB,CAAC;IAChC,WAAW,EAAE,mBAAmB,CAAC;IACjC,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,UAAU,IAAI,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,gBAAgB,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAe9G;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CA0P/E"}