primitive-admin 1.1.0-alpha.9 → 1.2.0-alpha.0

package/dist/src/lib/app-settings-descriptor.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Shared field descriptor for app-settings TOML sync (issue #1033).
+ *
+ * A single source of truth describing every app setting that round-trips
+ * through `app.toml`. It drives BOTH directions:
+ *  - pull  (`serializeAppSettingsToToml`): server settings -> `app.toml` object
+ *  - push  (`parseTomlToAppSettings`):     `app.toml` object -> settings payload
+ *
+ * Driving serializer and parser from one table means the two can never drift
+ * apart, and a single drift test can assert the descriptor stays in step with
+ * the server's `GET /settings` response and `PUT /settings` allow-list. This
+ * generalizes the earlier hand-maintained `AUTH_BOOLEAN_KEYS` /
+ * `RECOGNIZED_AUTH_KEYS` pattern to every section, and fully replaces it.
+ *
+ * Design decisions of record (issue #1033):
+ *  - Google is a typed client MAP (#2891): `googleClients` renders as
+ *    `[auth.google.clients.<type>]`, and each entry's `clientSecret` holds a
+ *    whole `{{secrets.KEY}}` reference rather than the secret itself, so the
+ *    map round-trips through `app.toml` like any other setting.
+ *  - `[cors]` is always emitted (the `mode` key is `emit: "always"`), even in
+ *    universal mode. A one-time diff on the next pull for existing apps is
+ *    acceptable.
+ *  - `[invitations]` is an additive table for the member-invitation fields.
+ *  - Nothing is writable-but-excluded any more (#2891). The legacy passkey
+ *    pair and the three Google/redirect scalars are RETIRED: not writable, not
+ *    synced, and refused by name with their own guidance when an old
+ *    `app.toml` still carries them.
+ *  - Push type mismatches are field-named validation errors — no silent
+ *    coercion of a mistyped TOML value.
+ *  - THE FILE IS THE WHOLE TRUTH (#2880, sponsor 2026-08-21). `app.toml` used
+ *    to be the one surface where an omitted key preserved the server's value,
+ *    while every other type follows "the local file is the source of truth"
+ *    (#1567). That exception is gone: push emits a value for EVERY writable
+ *    field, and a key the file does not carry clears the field or resets it to
+ *    its declared default (`APP_SETTINGS_ABSENT_VALUES`). `[app].name` and
+ *    `[app].mode` are the two exceptions — no default, identity-critical, and
+ *    `mode: null` is a 400 — so their absence is a validation error instead.
+ */
+/** The value shape of a synced setting. Drives serialization + push validation. */
+export type AppSettingType = "string" | "boolean" | "number" | "string[]" | "object";
+/** The `app.toml` section a setting lives under. */
+export type AppSettingSection = "app" | "auth" | "cors" | "invitations";
+export interface AppSettingDescriptor {
+    /** Server settings key — matches the `GET`/`PUT /settings` field name. */
+    field: string;
+    /** `app.toml` section the key lives under. */
+    section: AppSettingSection;
+    /** Key within the section (often equal to `field`, e.g. `corsMode` -> `mode`). */
+    key: string;
+    /** Value type; drives pull serialization and push-side type validation. */
+    type: AppSettingType;
+    /**
+     * `"always"` — emit on pull even when empty (empty array / `false` / default),
+     *   but never when the value is `null`/`undefined` (TOML cannot encode null).
+     * `"whenSet"` — omit when the value is "empty" (`null`/`undefined`/`""`/`[]`/`{}`).
+     */
+    emit: "always" | "whenSet";
+}
+/**
+ * Every field that round-trips through `app.toml` — DERIVED from the
+ * `app-settings` configuration-object definition (#2644), not listed.
+ *
+ * The definition already states each field's section (its table's TOML path),
+ * its `app.toml` key, its type and its `emit` rule, and the coverage guard
+ * holds it against the `App` model. Restating those 26 entries here made
+ * adding a setting two edits that a parity test then compared — the "two lists
+ * and a test they agree" shape the design gate rejected (2026-08-12). One edit
+ * in the definition now reaches the server allow-list
+ * (`settings-fields.ts`), this descriptor, and both directions of the sync.
+ *
+ * `json` in the definition is this module's `object` — the same shape under the
+ * name each side has always used for it.
+ */
+export declare const APP_SETTINGS_DESCRIPTOR: readonly AppSettingDescriptor[];
+/**
+ * Section render order for a stable, diff-friendly `app.toml` — the
+ * definition's table order (#2644), so a new section is rendered by being
+ * declared there.
+ */
+export declare const APP_SETTINGS_SECTIONS: readonly AppSettingSection[];
+/**
+ * `GET /settings` keys that are computed/read-only and never sync (no server
+ * setter). The external coverage drift test classifies these here.
+ */
+export declare const IGNORED_GET_KEYS: ReadonlySet<string>;
+/**
+ * Fields that ARE still writable server-side (present in the `PUT /settings`
+ * allow-list) but are deliberately excluded from TOML because a newer field
+ * supersedes them. Kept distinct from `IGNORED_GET_KEYS` so the coverage test's
+ * "every allow-listed field is covered" claim stays true — these are excluded,
+ * not read-only. (Codex design-review concern #1.)
+ */
+export declare const DEPRECATED_WRITABLE_EXCLUDED: ReadonlySet<string>;
+/**
+ * What push sends for a field the file does not carry (#2880 criterion 4).
+ *
+ * `"required"` means the key may not be omitted at all; every other entry is
+ * the value the PUT receives, chosen so it lands the server exactly where its
+ * `GET /settings` read default already reports the field when nothing is
+ * stored. That equality is the whole point: it makes a `config pull` (which
+ * omits `emit: "whenSet"` values that are empty) followed by a `config push` a
+ * no-op, and it makes an absent key compare equal to the server's materialized
+ * default rather than as a difference no push could clear.
+ *
+ * The vendored surface declares no defaults, so the table is authored here and
+ * asserted field-by-field against the controller's read defaults by
+ * `app-settings-absent-values-2880.test.ts` — a new setting fails that test
+ * (and `appSettingAbsentValue` below) rather than silently clearing.
+ *
+ * | absent key | sent | why |
+ * |---|---|---|
+ * | `name`, `mode` | — | required: no server default, identity-critical, and `mode: null` is a 400 |
+ * | `waitlistEnabled`, `passkeyEnabled`, `memberInvitationsEnabled`, `corsAllowCredentials` | `false` | the read default (`!!` / strict bool) |
+ * | `emailSignInEnabled`, `waitlistNotifyAdmins` | `true` | the read default (`isEmailSignInEnabled` / `!== false`) |
+ * | `memberInvitationLimit` | `5` | the read default (`?? 5`) |
+ * | `corsMode` | `"universal"` | the read default (`|| "universal"`) |
+ * | `googleOAuthEnabled`, `appleSignInEnabled` | `null` | tri-state: null is "auto", not "off" |
+ * | everything else | `null` | clears |
+ */
+export type AppSettingAbsentValue = {
+    required: true;
+} | {
+    required?: false;
+    value: unknown;
+};
+export declare const APP_SETTINGS_ABSENT_VALUES: Readonly<Record<string, AppSettingAbsentValue>>;
+/**
+ * The absent-key rule for one field, or a loud failure.
+ *
+ * Deliberately a throw rather than a `?? null` fallback: under whole-truth push
+ * an unlisted field would be CLEARED on every push by a table nobody updated.
+ */
+export declare function appSettingAbsentValue(field: string): AppSettingAbsentValue;
+/** Fields whose absence is a validation error rather than a clear (#2880). */
+export declare const REQUIRED_APP_SETTING_FIELDS: readonly string[];
+/**
+ * The value the SERVER would hold after accepting this one (#2880 DSO-003).
+ *
+ * The comparison runs on the local side only: push forwards what the file says
+ * and the server normalizes it, so without this an authored-but-noncanonical
+ * value (`baseUrl` with a trailing slash, a mixed-case test-account email)
+ * differs from the record the server returns FOREVER — and baseline restamping
+ * cannot save it, because after an apply the remote hash matches the new
+ * baseline while the local hash still does not, re-classifying `local-edited`
+ * on every run.
+ *
+ * Mirrors the rules in `settings-controller.ts` (`baseUrl` trim + trailing
+ * slash), `validateTestAccountBaseEmails` (trim, lower-case, dedupe) and
+ * `validateRedirectUris` (trim, dedupe). Only the NORMALIZATION is mirrored,
+ * never the rejection: an entry the server would refuse stays as authored so
+ * the server's own 400 is what the operator sees.
+ */
+export declare function canonicalizeAppSettingValue(field: string, value: unknown): unknown;
+/**
+ * One field's comparable value — what `config diff` and the push gate both read.
+ *
+ * Canonicalized as above, then flattened to `null` when the value is "empty"
+ * under an `emit: "whenSet"` field's own rule. That second step is the
+ * app-settings copy of what `projectConfigForComparison` does for every other
+ * type (#2731): pull OMITS an empty `whenSet` value, so the file it round-trips
+ * to has no key, and comparing `[]` against "no key" would be a difference no
+ * push could ever converge.
+ */
+export declare function comparableAppSettingValue(descriptor: AppSettingDescriptor, value: unknown): unknown;
+/**
+ * Project a settings record (either side) onto the full writable field set.
+ *
+ * `excludeName` is the cross-app rule (#2880 DSO-001): while a cross-app push's
+ * name exclusion is active, BOTH sides and the stamped baseline are hashed
+ * without `name`, so `classifyPushChange`'s `remoteHash === baselineHash ⇒
+ * local-edited` arithmetic stays valid.
+ */
+export declare function projectAppSettingsForComparison(settings: Record<string, any> | null | undefined, options?: {
+    excludeName?: boolean;
+}): Record<string, unknown>;
+/** Descriptor `field` names, for parity/coverage tests. */
+export declare const DESCRIPTOR_FIELDS: ReadonlySet<string>;
+/**
+ * Build one `app.toml` section object from server settings (pull direction).
+ * Applies each field's `emit` rule; a `null` value is always omitted (TOML
+ * cannot encode null).
+ */
+export declare function serializeSection(settings: Record<string, any>, section: AppSettingSection): Record<string, any>;
+/**
+ * Build the full `app.toml` data object (all sections) from server settings.
+ * Empty sections are omitted, though in practice every section has at least one
+ * `emit: "always"` key so all four are present.
+ */
+export declare function serializeAppSettingsToToml(settings: Record<string, any>): Record<string, any>;
+export interface ParsedSettingsResult {
+    /** Settings payload to send to `PUT /settings` (only keys present in TOML). */
+    settings: Record<string, any>;
+    /**
+     * Non-fatal issues — surfaced but not blocking. Unrecognized keys used to
+     * land here; #2644 criterion 6 made them errors, so this is now the slot for
+     * anything advisory a later rule adds.
+     */
+    warnings: string[];
+    /** Fatal issues (unrecognized key or table, type mismatch) — push aborts. */
+    errors: string[];
+}
+/**
+ * Translate a parsed `app.toml` object into the settings the FILE STATES —
+ * only the keys it carries. This is the parse half; `buildAppSettingsPayload`
+ * below turns it into the whole-truth `PUT /settings` body by filling in what
+ * the file omits. An unrecognized key or table and a type
+ * mismatch are both hard errors the caller must treat as abort-before-PUT
+ * (#2644 criterion 6: push rejects what it does not recognize, for every
+ * configuration surface, so a typo fails locally instead of being ignored).
+ *
+ * A per-entry `clientSecret` that is not a whole `{{secrets.KEY}}` reference is
+ * the server's rejection to make (#2256): the push forwards the map and the
+ * `PUT` answers 400 with `GOOGLE_CLIENT_SECRET_MUST_BE_SECRET_REF`. Duplicating
+ * the shape rule here would put two definitions of "valid reference" in play.
+ *
+ * A RETIRED key (#2891) is different: it is not a value the server can judge,
+ * it is a line that has to be deleted, so the parser refuses it locally with
+ * the guidance that names its replacement.
+ *
+ * `isCrossAppPush` — or `excludeName`, the same rule as the caller computed it
+ * (#2880 DSO-001, `appSettingsNameExcluded`) — strips `name` so a cross-app
+ * push never overwrites the target app's name. The strip has to happen HERE and
+ * not only in the payload builder below (#2936): a field the body will not
+ * carry is not a field this file gets to refuse, or a slot bound to another app
+ * aborts diff and push over a `[app].name` neither of them was going to send.
+ */
+export declare function parseTomlToAppSettings(tomlData: Record<string, any>, options?: {
+    isCrossAppPush?: boolean;
+    excludeName?: boolean;
+}): ParsedSettingsResult;
+/**
+ * `[app].name` / `[app].mode` absent — the two keys whole-truth push refuses to
+ * fill in for the author (#2880).
+ *
+ * Read from the DOCUMENT rather than the parse result, so a cross-app push
+ * (which strips `name` before validating) still requires the file to state one.
+ * `mode` has no default and `mode: null` is a 400; more to the point, a deleted
+ * `mode` line silently resetting an invite-only app to public is the wrong
+ * failure to choose.
+ */
+export declare function missingRequiredKeyErrors(tomlData: Record<string, any>): string[];
+/**
+ * The whole-truth `PUT /settings` body (#2880 criterion 4).
+ *
+ * Every writable field gets a value: the authored one where the file carries
+ * the key, its `APP_SETTINGS_ABSENT_VALUES` entry where it does not. That is
+ * what makes `app.toml` mean what every other configuration file means — the
+ * local file is the state, not a patch over whatever the server happens to
+ * hold (#1567). The controller applies only the keys in the body (`if (field in
+ * updates)`), so the completeness has to come from here.
+ *
+ * Values are forwarded AS AUTHORED, never canonicalized: the server owns its
+ * own normalization, and a CLI that rewrote the value before sending it would
+ * be pushing something the operator did not write. The canonicalization in
+ * `canonicalizeAppSettingValue` is for the local COMPARISON only.
+ *
+ * `excludeName` (and `isCrossAppPush`, which implies it) leaves `name` out of
+ * the body entirely, so a cross-app push never renames the target app.
+ */
+export declare function buildAppSettingsPayload(tomlData: Record<string, any>, options?: {
+    isCrossAppPush?: boolean;
+    excludeName?: boolean;
+}): ParsedSettingsResult;