@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/dist/modules/settings/connection-check.d.ts

@@ -0,0 +1,118 @@
+import { type IGitRunner } from '../../shared/git.contract.js';
+/** The repository connection a deployment reads and writes its knowledge base with. */
+export interface RepositoryConnection {
+    url: string;
+    token: string;
+    username: string;
+}
+/** Which form field a failed check is about — the save reports it against that input. */
+export type ConnectionField = 'kbRepoUrl' | 'gitToken';
+/** What the remote listed, when it answered a read. */
+interface Listing {
+    branches: string[];
+    /** What the remote calls its own trunk, when it says. */
+    defaultBranch: string | null;
+    /** No branches yet — a supported starting point, not a failure. */
+    empty: boolean;
+}
+/**
+ * The three answers a connection can give, and the only three the screen
+ * distinguishes:
+ *
+ *  - `connected`: the token reads AND writes the repository;
+ *  - `read-only`: it reads, but the host refused the push side — the listing
+ *    rides along, and `error` names the permission to grant;
+ *  - `rejected`: it never got as far as reading — bad credentials, no such
+ *    repository, or a host that could not be reached.
+ */
+export type ConnectionCheck = ({
+    outcome: 'connected';
+} & Listing) | ({
+    outcome: 'read-only';
+    field: 'gitToken';
+    error: string;
+} & Listing) | {
+    outcome: 'rejected';
+    reason: FailureReason;
+    field: ConnectionField;
+    error: string;
+};
+export type FailureReason = 'credentials' | 'not-found' | 'unreachable' | 'invalid-address' | 'unknown';
+/** Runs one git command; rejects with an error whose message carries git's stderr. */
+export type GitRunner = (args: string[], env: NodeJS.ProcessEnv) => Promise<{
+    stdout: string;
+}>;
+/**
+ * The probe's git, run through the deployment's git port (see
+ * `shared/git.contract.ts`) so it carries the same environment, deadline
+ * handling and token redaction as every other git the backend runs — and so
+ * a host that never answers is killed with its helpers rather than left
+ * holding a request open.
+ */
+export declare function gitRunnerFor(runner: IGitRunner): GitRunner;
+/**
+ * The `-c` pairs that authenticate one probe invocation — the connection
+ * check and the root-folder listing alike, so a token reaches git ONE way.
+ * The helper reads the token from the environment at call time, so it never
+ * appears in argv (and so never in a process listing or a crash dump); the
+ * empty helper first clears any the host has configured, so the answer is
+ * about THIS token, not one sitting in a system credential store. The
+ * username is interpolated into the snippet, which is why the callers refuse
+ * anything but a plain one before it gets here.
+ */
+export declare function probeCredentialArgs(username: string, token: string): string[];
+/** The environment a probe invocation runs with: the token, and no prompts. */
+export declare function probeGitEnv(token: string): NodeJS.ProcessEnv;
+/** The check bound to one runner: what the composition root hands the setup routes. */
+export declare function repositoryConnectionCheck(runner: IGitRunner): (connection: RepositoryConnection) => Promise<ConnectionCheck>;
+/**
+ * Ask the remote whether this connection can do what a deployment needs of it:
+ * READ the repository and WRITE to it, with exactly the token and username the
+ * deployment will use.
+ *
+ * Reading alone is not enough. A read-only token lists branches, clones, and
+ * finishes setup — and then every save anyone makes fails at push, which is
+ * the first moment anyone would learn the token was wrong.
+ *
+ *  - Read: `ls-remote` of HEAD and the branches, the cheapest call that proves
+ *    the address resolves and the credential authenticates.
+ *  - Write: a DRY-RUN push deleting a ref that does not exist, from an empty
+ *    scratch repository. Nothing is sent and nothing can be written, but git
+ *    still opens `receive-pack`, which is where a host checks push permission.
+ *    A host that lets us that far answers "remote ref does not exist" (or,
+ *    locally, reports the no-op delete) — either is a yes.
+ *
+ * The ONE function both Test connection and the settings save call, so the
+ * button can never say "connected" about a connection the save would refuse.
+ */
+export declare function checkRepositoryConnection(connection: RepositoryConnection, run?: GitRunner): Promise<ConnectionCheck>;
+/**
+ * Why a READ failed — the shared classifier's reading (`shared/git-failure.ts`,
+ * the ONE table of git's wordings), in the three reasons the connection check
+ * reports. This module keeps no patterns of its own: a host that changes its
+ * phrasing is learned once, for this check and the KB startup phase alike.
+ */
+export declare function classifyReadFailure(text: string): FailureReason;
+/**
+ * What a dry-run push's failure means, given the same credentials have just
+ * READ the repository.
+ *
+ * "remote ref does not exist" is git's answer AFTER the host has let it into
+ * `receive-pack` and advertised its refs — the probe ref is absent by design,
+ * so that answer is proof of write access, not a failure. It is this probe's
+ * own success signal, which is why it is read here rather than in the shared
+ * table of failures.
+ *
+ * Everything else is the shared classifier's reading of a WRITE: a refusal in
+ * a host's own words, or a bare 403/404 (the credentials just listed the
+ * repository, so it exists and the host is hiding the write side), is
+ * read-only; an authentication failure stays credentials — on a PUBLIC
+ * repository the read succeeds anonymously, so the push is the first time the
+ * token is presented, and a made-up one must not send the admin off to grant a
+ * permission to a token that does not exist.
+ */
+export declare function classifyWriteFailure(text: string): 'writable' | 'read-only' | FailureReason;
+/** The permission a token needs to write, in the host's own words where it is recognised. */
+export declare function writePermissionFor(url: string): string;
+export {};
+//# sourceMappingURL=connection-check.d.ts.map

package/dist/modules/settings/connection-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-check.d.ts","sourceRoot":"","sources":["../../../src/modules/settings/connection-check.ts"],"names":[],"mappings":"AAOA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAG5E,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yFAAyF;AACzF,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,UAAU,CAAC;AAEvD,uDAAuD;AACvD,UAAU,OAAO;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mEAAmE;IACnE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GACvB,CAAC;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,GAAG,OAAO,CAAC,GACpC,CAAC;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,GACtE;IACE,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,WAAW,GAAG,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAExG,sFAAsF;AACtF,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAWhG;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAK1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ7E;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAS5D;AAED,uFAAuF;AACvF,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,UAAU,GACjB,CAAC,UAAU,EAAE,oBAAoB,KAAK,OAAO,CAAC,eAAe,CAAC,CAGhE;AASD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,oBAAoB,EAChC,GAAG,GAAE,SAAoB,GACxB,OAAO,CAAC,eAAe,CAAC,CAsE1B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAW/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,CAe3F;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAgBtD"}

package/dist/modules/settings/connection-check.js

@@ -0,0 +1,287 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { validateHttpsRemote } from './deployment-settings.service.js';
+import { classifyGitFailure } from '../../shared/git-failure.js';
+import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
+import { GitRunError } from '../../shared/git.contract.js';
+import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+const TOKEN_ENV = 'BEVEL_PROBE_TOKEN';
+/**
+ * A short deadline of its own: this is an interactive check behind a form,
+ * and an admin waiting on a wrong URL should hear so in seconds, not after
+ * the port's default.
+ */
+const PROBE_TIMEOUT_MS = 20_000;
+/**
+ * The probe's git, run through the deployment's git port (see
+ * `shared/git.contract.ts`) so it carries the same environment, deadline
+ * handling and token redaction as every other git the backend runs — and so
+ * a host that never answers is killed with its helpers rather than left
+ * holding a request open.
+ */
+export function gitRunnerFor(runner) {
+    return async (args, env) => {
+        const { stdout } = await runner.run(process.cwd(), args, { env, timeoutMs: PROBE_TIMEOUT_MS });
+        return { stdout };
+    };
+}
+/**
+ * The `-c` pairs that authenticate one probe invocation — the connection
+ * check and the root-folder listing alike, so a token reaches git ONE way.
+ * The helper reads the token from the environment at call time, so it never
+ * appears in argv (and so never in a process listing or a crash dump); the
+ * empty helper first clears any the host has configured, so the answer is
+ * about THIS token, not one sitting in a system credential store. The
+ * username is interpolated into the snippet, which is why the callers refuse
+ * anything but a plain one before it gets here.
+ */
+export function probeCredentialArgs(username, token) {
+    return [
+        '-c',
+        'credential.helper=',
+        ...(token
+            ? ['-c', `credential.helper=!f() { printf '%s\\n' "username=${username}" "password=$${TOKEN_ENV}"; }; f`]
+            : []),
+    ];
+}
+/** The environment a probe invocation runs with: the token, and no prompts. */
+export function probeGitEnv(token) {
+    return {
+        ...process.env,
+        [TOKEN_ENV]: token,
+        // Never let git stop for a prompt: without this a bad credential hangs the
+        // request until the timeout instead of failing.
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_ASKPASS: 'echo',
+    };
+}
+/** The check bound to one runner: what the composition root hands the setup routes. */
+export function repositoryConnectionCheck(runner) {
+    const run = gitRunnerFor(runner);
+    return (connection) => checkRepositoryConnection(connection, run);
+}
+let defaultRun = null;
+/** The check's own runner when none is injected — a port with default settings, made once. */
+function runGit() {
+    defaultRun ??= gitRunnerFor(new NodeGitRunner());
+    return defaultRun;
+}
+/**
+ * Ask the remote whether this connection can do what a deployment needs of it:
+ * READ the repository and WRITE to it, with exactly the token and username the
+ * deployment will use.
+ *
+ * Reading alone is not enough. A read-only token lists branches, clones, and
+ * finishes setup — and then every save anyone makes fails at push, which is
+ * the first moment anyone would learn the token was wrong.
+ *
+ *  - Read: `ls-remote` of HEAD and the branches, the cheapest call that proves
+ *    the address resolves and the credential authenticates.
+ *  - Write: a DRY-RUN push deleting a ref that does not exist, from an empty
+ *    scratch repository. Nothing is sent and nothing can be written, but git
+ *    still opens `receive-pack`, which is where a host checks push permission.
+ *    A host that lets us that far answers "remote ref does not exist" (or,
+ *    locally, reports the no-op delete) — either is a yes.
+ *
+ * The ONE function both Test connection and the settings save call, so the
+ * button can never say "connected" about a connection the save would refuse.
+ */
+export async function checkRepositoryConnection(connection, run = runGit()) {
+    const { url, token, username } = connection;
+    // The callers validate what they are sent; this is the floor under them,
+    // because both values reach git (the URL as an argument, the username inside
+    // a shell snippet) and either unvalidated is injection. The URL is ANSWERED,
+    // not thrown: one stored before the rule tightened (userinfo) still arrives
+    // here through a save that only changes the token, and the admin needs the
+    // rule's own words against the address — not a 500.
+    const urlProblem = validateHttpsRemote(url);
+    if (urlProblem) {
+        return { outcome: 'rejected', reason: 'invalid-address', field: 'kbRepoUrl', error: urlProblem };
+    }
+    if (!/^[A-Za-z0-9._-]+$/.test(username))
+        throw new Error('Refusing an unsupported git username.');
+    const credArgs = probeCredentialArgs(username, token);
+    const env = probeGitEnv(token);
+    /** What git said, as git said it — the classifier's input. */
+    const gitSaid = (err) => {
+        let raw = err instanceof Error ? err.message : String(err);
+        // The port carries git's stderr beside the message, and that is where the
+        // host's own words are — the classifier reads them.
+        if (err instanceof GitRunError && err.stderr)
+            raw += `\n${err.stderr}`;
+        // A deadline expiry says so in `timedOut` (the port) or in `killed` /
+        // `signal` (a bare execFile) — never in the message. Without the marker a
+        // host that never answers classifies as `unknown`, not unreachable.
+        const exit = err;
+        if ((err instanceof GitRunError && err.timedOut) || (exit?.killed && exit.signal === 'SIGTERM')) {
+            raw += '\ntimed out';
+        }
+        return raw;
+    };
+    // Classification reads the raw text; only a scrubbed copy is ever echoed —
+    // git failures have been known to quote the credential back.
+    const scrub = (text) => redactSecret(text, [token, ...urlQuerySecrets(url)]);
+    let listing;
+    try {
+        // `--end-of-options` on top of the validation above: belt and braces, so
+        // nothing that arrives here can ever be read as a flag. Patterns, not
+        // `--heads`: `--heads` drops the HEAD symref, and with it the default branch.
+        const { stdout } = await run([...credArgs, 'ls-remote', '--symref', '--end-of-options', url, 'HEAD', 'refs/heads/*'], env);
+        listing = parseListing(stdout);
+    }
+    catch (err) {
+        const raw = gitSaid(err);
+        return rejection(classifyReadFailure(raw), scrub(raw));
+    }
+    const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'hexis-write-check-'));
+    try {
+        await run(['init', '--bare', '--quiet', scratch], env);
+        const probeRef = `refs/heads/hexis-write-check-${randomBytes(6).toString('hex')}`;
+        await run([...credArgs, `--git-dir=${scratch}`, 'push', '--dry-run', '--end-of-options', url, `:${probeRef}`], env);
+        return { outcome: 'connected', ...listing };
+    }
+    catch (err) {
+        const raw = gitSaid(err);
+        const verdict = classifyWriteFailure(raw);
+        if (verdict === 'writable')
+            return { outcome: 'connected', ...listing };
+        if (verdict === 'read-only') {
+            return { outcome: 'read-only', field: 'gitToken', error: readOnlyMessage(url), ...listing };
+        }
+        return rejection(verdict, scrub(raw));
+    }
+    finally {
+        await fs.rm(scratch, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/**
+ * Why a READ failed — the shared classifier's reading (`shared/git-failure.ts`,
+ * the ONE table of git's wordings), in the three reasons the connection check
+ * reports. This module keeps no patterns of its own: a host that changes its
+ * phrasing is learned once, for this check and the KB startup phase alike.
+ */
+export function classifyReadFailure(text) {
+    switch (classifyGitFailure(text, { operation: 'read' }).kind) {
+        case 'credentials-rejected':
+            return 'credentials';
+        case 'not-found':
+            return 'not-found';
+        case 'unreachable':
+            return 'unreachable';
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * What a dry-run push's failure means, given the same credentials have just
+ * READ the repository.
+ *
+ * "remote ref does not exist" is git's answer AFTER the host has let it into
+ * `receive-pack` and advertised its refs — the probe ref is absent by design,
+ * so that answer is proof of write access, not a failure. It is this probe's
+ * own success signal, which is why it is read here rather than in the shared
+ * table of failures.
+ *
+ * Everything else is the shared classifier's reading of a WRITE: a refusal in
+ * a host's own words, or a bare 403/404 (the credentials just listed the
+ * repository, so it exists and the host is hiding the write side), is
+ * read-only; an authentication failure stays credentials — on a PUBLIC
+ * repository the read succeeds anonymously, so the push is the first time the
+ * token is presented, and a made-up one must not send the admin off to grant a
+ * permission to a token that does not exist.
+ */
+export function classifyWriteFailure(text) {
+    if (/remote ref does not exist/i.test(text))
+        return 'writable';
+    switch (classifyGitFailure(text, { operation: 'write' }).kind) {
+        case 'write-refused':
+        case 'push-refused-by-policy':
+            return 'read-only';
+        case 'credentials-rejected':
+            return 'credentials';
+        case 'not-found':
+            return 'not-found';
+        case 'unreachable':
+            return 'unreachable';
+        default:
+            return 'unknown';
+    }
+}
+/** The permission a token needs to write, in the host's own words where it is recognised. */
+export function writePermissionFor(url) {
+    let host = '';
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        // Unreachable in practice — the URL was validated before it was probed.
+    }
+    if (host === 'github.com' || host.endsWith('.github.com')) {
+        return 'on GitHub, “Contents: Read and write” for this repository (a classic token needs the “repo” scope)';
+    }
+    if (host === 'gitlab.com')
+        return 'on GitLab, the “write_repository” scope and at least the Developer role';
+    if (host === 'bitbucket.org')
+        return 'on Bitbucket, “Repositories: Write”';
+    if (host === 'dev.azure.com' || host.endsWith('.visualstudio.com')) {
+        return 'on Azure DevOps, “Code: Read & write”';
+    }
+    return 'push (write) access to this repository';
+}
+function readOnlyMessage(url) {
+    return `This token can read the repository but cannot write to it. Grant it write access: ${writePermissionFor(url)}.`;
+}
+function rejection(reason, text) {
+    switch (reason) {
+        case 'credentials':
+            return {
+                outcome: 'rejected',
+                reason,
+                field: 'gitToken',
+                error: 'The host rejected those credentials. Check the token, and that the username matches the host (GitHub x-access-token, GitLab oauth2, Bitbucket x-token-auth).',
+            };
+        case 'not-found':
+            return {
+                outcome: 'rejected',
+                reason,
+                field: 'kbRepoUrl',
+                error: 'No repository at that URL — or the token cannot see it.',
+            };
+        case 'unreachable':
+            return {
+                outcome: 'rejected',
+                reason,
+                field: 'kbRepoUrl',
+                error: 'Could not reach that host from this server. Check the URL and any network egress rules, then try again.',
+            };
+        default:
+            // Echoed only when it matches nothing known, already scrubbed of the
+            // token — `ls-remote` failures have been known to quote the credential.
+            return {
+                outcome: 'rejected',
+                reason: 'unknown',
+                field: 'kbRepoUrl',
+                error: text.split('\n').slice(0, 3).join(' ').slice(0, 400),
+            };
+    }
+}
+/** `<sha>\trefs/heads/<name>` rows, plus the `ref: … HEAD` symref row when a host sends one. */
+function parseListing(stdout) {
+    const lines = stdout.split('\n');
+    // Tag refs and the bare HEAD row are not branches, so they are filtered
+    // rather than sliced blindly.
+    const branches = lines
+        .filter((line) => !line.startsWith('ref:'))
+        .map((line) => line.split('\t')[1]?.trim())
+        .filter((ref) => !!ref && ref.startsWith('refs/heads/'))
+        .map((ref) => ref.slice('refs/heads/'.length));
+    const defaultBranch = lines
+        .find((line) => line.startsWith('ref:') && line.trimEnd().endsWith('\tHEAD'))
+        ?.slice('ref: refs/heads/'.length)
+        .split('\t')[0]
+        ?.trim() || null;
+    return { branches, defaultBranch, empty: branches.length === 0 };
+}
+//# sourceMappingURL=connection-check.js.map

package/dist/modules/settings/connection-check.js.map

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

package/dist/modules/settings/deployment-settings.service.d.ts

@@ -1,4 +1,5 @@
 import type { Database } from '../database/connection.js';
+import { type KbLayout } from '@bevel-software/platform-shared';
 /**
  * A setting an admin may set from the setup screen instead of the environment.
  *
@@ -8,7 +9,18 @@ import type { Database } from '../database/connection.js';
  */
 export interface SettingDef {
     key: string;
-    envVar: string;
+    /**
+     * The environment variable that still WINS over a stored row, when there is
+     * one — see {@link DeploymentSettingsService}.
+     *
+     * Absent for the knowledge-base layout (the three root folders and the agent
+     * guide's file name): those are entered in the app and nowhere else. They had
+     * variables once; a deployment that still sets one gets its value imported
+     * into the saved setting on the first boot after the upgrade, and the
+     * variable ignored from then on (see
+     * {@link DeploymentSettingsService.importLegacyLayoutEnv}).
+     */
+    envVar?: string;
     /** Which block of the setup screen it belongs to. */
     section: 'knowledge-base' | 'sign-in';
     secret?: boolean;
@@ -20,6 +32,17 @@ export interface SettingDef {
      * was copied into a service at construction is not.
      */
     restartToApply?: boolean;
+    /**
+     * What an UNSET setting already means to the code that reads it — the
+     * layout's defaults, the pointer consent's "on unless turned off".
+     *
+     * Only `restartToApply` settings need it, and only for one question: saving
+     * a value the deployment is ALREADY running on changes nothing, so it owes
+     * no restart. Without it, ticking a box that was ticked all along, or typing
+     * `AGENTS.md` into a field that was showing `AGENTS.md`, tells the admin to
+     * restart for a change that never happened.
+     */
+    unsetMeans?: string;
 }
 /**
  * The one rule for what a KB remote may look like, shared by the setting below
@@ -33,11 +56,38 @@ export declare const validateHttpsRemote: (value: string) => string | null;
  * The core catalogue. Order is the order the setup screen renders them in.
  */
 export declare const CORE_SETTINGS: SettingDef[];
+/**
+ * The environment variables the KB layout USED to be read from, and the
+ * settings they now live in. Referenced only by
+ * {@link DeploymentSettingsService.importLegacyLayoutEnv} — nothing else may
+ * read them, or they would be back to being a second source of truth. The
+ * guide's file name is deliberately absent: it never had a variable, so there
+ * is nothing to import.
+ */
+export declare const LEGACY_LAYOUT_ENV_VARS: Readonly<Record<string, string>>;
+/**
+ * Whether the single sign-on configuration in effect is known to work:
+ * `verified` (the provider accepted its credentials, or someone signed in with
+ * it), `unverified` (configured, never proven — sign in once to confirm), or
+ * `not-configured` (no issuer, application id and secret to prove), or
+ * `unrecordable` (configured, but SECRETS_ENC_KEY is unset — see
+ * {@link DeploymentSettingsService.oidcVerification}).
+ */
+export type OidcVerificationState = 'verified' | 'unverified' | 'not-configured' | 'unrecordable';
+/** What a record can say about one set of values. */
+export type OidcRecordState = 'verified' | 'unverified';
+/** The three values a verification is about. Scopes, label and domains are not among them. */
+export interface OidcCredentials {
+    issuerUrl: string;
+    clientId: string;
+    clientSecret: string;
+}
 /** Where a resolved value came from, which is what the UI renders as its status. */
 export type SettingSource = 'env' | 'stored' | 'unset';
 export interface ResolvedSetting {
     key: string;
-    envVar: string;
+    /** Omitted for a setting no environment variable can override. */
+    envVar?: string;
     section: SettingDef['section'];
     source: SettingSource;
     /** Omitted entirely for secrets — `configured` is all a client ever learns. */
@@ -58,6 +108,14 @@ export interface ResolvedSetting {
  *  - and "why is it not using my env var" never becomes a question, because
  *    the answer is always "it is".
  *
+ * ONE EXCEPTION, and it is a setting-by-setting one rather than a hole in the
+ * rule: a definition with no {@link SettingDef.envVar} has no variable to be
+ * outranked by. That is the knowledge-base layout — the three root folders and
+ * the agent guide's file name — which is deployment configuration entered once
+ * in the app. The three variables it used to read are imported into their saved
+ * settings on the first boot after the upgrade ({@link
+ * DeploymentSettingsService.importLegacyLayoutEnv}) and ignored after that.
+ *
  * Values are cached in memory after {@link load}. Reads happen on every clone
  * and every git call, and a database round-trip there would be a tax on the
  * hot path for data that changes about twice in a deployment's life.
@@ -69,6 +127,10 @@ export interface ResolvedSetting {
  * deployment that has nothing to serve until it is. Nobody is mid-session on a
  * second replica at that moment.
  *
+ * The single sign-on settings are the first to bend that: they apply live, so
+ * on a multi-replica deployment an OIDC change reaches only the replica that
+ * served the save until the others restart.
+ *
  * It stops being acceptable the moment a setting is something an operator
  * changes on a live multi-replica deployment. Adding one means adding
  * invalidation with it — the event bus already carries user-scoped and
@@ -77,6 +139,7 @@ export interface ResolvedSetting {
  */
 export declare class DeploymentSettingsService {
     private readonly db;
+    private readonly secretsEncKey;
     private readonly defs;
     private stored;
     private readonly crypto;
@@ -93,11 +156,36 @@ export declare class DeploymentSettingsService {
      * The KB layout in effect: each root from the environment, else the stored
      * row, else its default. The composition root applies this once at boot.
      */
-    resolveKbLayout(): {
-        knowledgeBaseDir: string;
-        skillsDir: string;
-        pluginsDir: string;
-    };
+    resolveKbLayout(): Required<KbLayout>;
+    /**
+     * Whether the platform should keep its pointer sentence in a customer-owned
+     * `AGENTS.md`. On unless the admin turned it off — an unset setting is a
+     * deployment that never saw the checkbox, and the sentence is what makes a
+     * renamed guide findable at all.
+     */
+    resolveAgentsFileLink(): boolean;
+    /**
+     * Import the retired layout environment variables into their saved settings,
+     * ONCE, on a deployment that still sets them.
+     *
+     * The three roots were environment-first until this release. Simply dropping
+     * the variables would put such a deployment back on `KnowledgeBase/`,
+     * `Skills/` and `Plugins/` at its next boot — against a repository laid out
+     * under other names, which is a knowledge base that scaffolds three empty
+     * folders and imports nothing. So on the first boot after the upgrade each
+     * still-set variable's value becomes the saved setting, and the log says the
+     * variable can be removed.
+     *
+     * Only where nothing is saved. A saved value is the admin's own answer,
+     * entered in the app, and it wins — with a warning, because a variable that
+     * no longer does anything is exactly the kind of thing someone later reads
+     * as the reason for a name. Equal values say nothing: there is nothing to
+     * tell anyone about.
+     *
+     * Called before `configureKbLayout`, so the boot that imports also RUNS on
+     * the imported names rather than on the defaults.
+     */
+    importLegacyLayoutEnv(): Promise<void>;
     /** Where {@link resolve} got its answer — what the setup screen labels the field with. */
     sourceOf(key: string): SettingSource;
     /**
@@ -114,10 +202,27 @@ export declare class DeploymentSettingsService {
      * A setting whose environment variable is set is REFUSED rather than silently
      * stored, because storing it would write a row that can never take effect and
      * leave the screen implying otherwise.
+     *
+     * `restartRequired` is this service's view: some restart-to-apply setting
+     * changed. It cannot know what the caller then applies to the running
+     * process, so `restartKeys` names the settings behind it — the setup route
+     * leaves out the folder names and the branch model when the save that
+     * completes setup has just applied them, and reports only what remains.
      */
     save(entries: Record<string, string>, updatedBy: string | null): Promise<{
         restartRequired: boolean;
+        restartKeys: string[];
     }>;
+    /**
+     * What {@link resolve} would answer for each key AFTER saving `entries` —
+     * validated by exactly the rules `save` applies, and throwing the same
+     * {@link SettingsValidationError}, but writing nothing. It is how a caller
+     * checks the values a save would put in effect (the repository connection)
+     * before letting the save happen.
+     */
+    resolveAfter(entries: Record<string, string>): (key: string) => string;
+    /** Validate a batch and return the writes it amounts to; throws on any problem. */
+    private plan;
     /** Drop stored rows for settings this build no longer defines. */
     prune(): Promise<void>;
     /**
@@ -127,6 +232,47 @@ export declare class DeploymentSettingsService {
      * a stored fallback, inverting the precedence everything else here obeys.
      */
     syncGitTokenEnv(): void;
+    /** The single sign-on values in effect, issuer normalized the way the provider uses it. */
+    resolveOidcCredentials(): OidcCredentials;
+    /**
+     * Whether the single sign-on configuration IN EFFECT is verified.
+     *
+     * The record names the values it was made about by a keyed digest, so it
+     * speaks only for those: a changed issuer, application id or secret —
+     * through a save or through the environment — reads as unverified until it
+     * is proven again, with nothing to remember to reset. The secret itself is
+     * never stored here, and a digest keyed with the secrets key cannot be
+     * checked against a guess without that key.
+     *
+     * WHICH IS WHY THERE IS NO RECORD WITHOUT THAT KEY: keyed with a public
+     * constant, the digest of a public issuer and application id would let
+     * anyone who can read `deployment_settings` (a backup, a replica, a dump)
+     * confirm guesses of the secret offline. A salt stored beside it would be
+     * read along with it. So with SECRETS_ENC_KEY unset nothing is recorded and
+     * a configured deployment reads `unrecordable`.
+     *
+     * Read from the database, not the in-memory cache: unlike the settings, this
+     * changes on a live deployment (every first sign-in), and a sign-in on one
+     * replica must show as Verified on the others.
+     */
+    oidcVerification(): Promise<OidcVerificationState>;
+    /** What is recorded about one set of single sign-on values — `unverified` when nothing is. */
+    oidcVerificationOf(credentials: OidcCredentials): Promise<OidcRecordState>;
+    /**
+     * Record what is known about one set of single sign-on values.
+     *
+     * ONLY EVER UPGRADES, atomically: `verified` overwrites, `unverified` only
+     * fills an empty slot. The same values cannot stop being proven by an
+     * inconclusive answer — an overlapping check that could not reach the token
+     * endpoint says nothing against the sign-in that worked.
+     *
+     * Records about values no longer in effect are left in place rather than
+     * swept: they are inert (nothing reads a key the current values do not hash
+     * to), and a sweep racing a save on another replica could delete the record
+     * of the values that end up in effect.
+     */
+    recordOidcVerification(state: OidcRecordState, credentials: OidcCredentials): Promise<void>;
+    private oidcVerificationKey;
     /** Remove one stored row (used by tests and by `prune`). */
     clear(key: string): Promise<void>;
 }