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

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,9 +9,20 @@ 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';
+    section: 'knowledge-base' | 'sign-in' | 'audit';
     secret?: boolean;
     /** Applied on save; the message is shown against the field. */
     validate?(value: string): string | null;
@@ -20,6 +32,25 @@ export interface SettingDef {
      * was copied into a service at construction is not.
      */
     restartToApply?: boolean;
+    /**
+     * A blank field on save CLEARS the stored value, putting the default back.
+     * The rule everywhere else is that blank means "leave it alone" — a stray
+     * Enter must not unconfigure a repository — and that stays the rule; this
+     * is for a setting whose readers already treat "unset" as its default, so
+     * clearing it is the one way back to that default and never a loss.
+     */
+    blankMeansDefault?: 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 +64,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 +116,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 +135,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 +147,7 @@ export interface ResolvedSetting {
  */
 export declare class DeploymentSettingsService {
     private readonly db;
+    private readonly secretsEncKey;
     private readonly defs;
     private stored;
     private readonly crypto;
@@ -93,11 +164,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 +210,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 (and the clears) it amounts to; throws on any problem. */
+    private plan;
     /** Drop stored rows for settings this build no longer defines. */
     prune(): Promise<void>;
     /**
@@ -127,6 +240,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>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"deployment-settings.service.d.ts","sourceRoot":"","sources":["../../../src/modules/settings/deployment-settings.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAU1D;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACxC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,KAAG,MAAM,GAAG,IAQ5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAAU,EAoKrC,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC/B,MAAM,EAAE,aAAa,CAAC;IACtB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,yBAAyB;IAMlC,OAAO,CAAC,QAAQ,CAAC,EAAE;IALrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAGzB,EAAE,EAAE,QAAQ,EAC7B,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,UAAU,EAAkB;IAQpC,IAAI,WAAW,IAAI,UAAU,EAAE,CAE9B;IAED,+EAA+E;IACzE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B3B;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAQ5B;;;OAGG;IACH,eAAe,IAAI;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAQtF,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAOpC;;;;OAIG;IACH,QAAQ,IAAI,eAAe,EAAE;IAgB7B;;;;;;;;OAQG;IACG,IAAI,CACR,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC;QAAE,eAAe,EAAE,OAAO,CAAA;KAAE,CAAC;IAkGxC,kEAAkE;IAC5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B;;;;;OAKG;IACH,eAAe,IAAI,IAAI;IAMvB,4DAA4D;IACtD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIxC;AAED,mFAAmF;AACnF,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;gBAAhC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAItD"}
+{"version":3,"file":"deployment-settings.service.d.ts","sourceRoot":"","sources":["../../../src/modules/settings/deployment-settings.service.ts"],"names":[],"mappings":"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"}