@cdmbase/wiki-browser 12.0.18-alpha.49 → 12.0.18-alpha.50

package/lib/templates/content/content-manifest.json

@@ -540,6 +540,27 @@
       "updatedAt": "Recently",
       "frontmatter": {}
     },
+    {
+      "contentId": "adminide-modules-preferences-contributes-configuration",
+      "slug": "preferences-contributes-configuration",
+      "filePath": "/content/docs/adminide-modules/preferences/contributes-configuration.md",
+      "relativePath": "adminide-modules/preferences/contributes-configuration.md",
+      "categoryId": "adminide-modules",
+      "title": "Contributes Configuration - defaultValueSource",
+      "description": "How to use defaultValueSource to resolve configuration defaults from vault secrets or environment variables",
+      "author": "Documentation",
+      "updatedAt": "2025-04-02T00:00:00",
+      "frontmatter": {
+        "meta": "",
+        "title": "Contributes Configuration - defaultValueSource",
+        "description": "How to use defaultValueSource to resolve configuration defaults from vault secrets or environment variables",
+        "date": "2025-04-02T00:00:00",
+        "updated": "2025-04-02T00:00:00",
+        "excerpt": "Contributes Configuration - defaultValueSource...",
+        "headers": "",
+        "Cache-Control": "no-cache"
+      }
+    },
     {
       "contentId": "adminide-modules-preferences-credentials-contribution",
       "slug": "preferences-credentials-contribution",
@@ -3877,6 +3898,15 @@
           "updatedAt": "Recently",
           "categoryId": "adminide-modules"
         },
+        {
+          "id": "adminide-modules-preferences-contributes-configuration",
+          "title": "Contributes Configuration - defaultValueSource",
+          "description": "How to use defaultValueSource to resolve configuration defaults from vault secrets or environment variables",
+          "slug": "preferences-contributes-configuration",
+          "author": "Documentation",
+          "updatedAt": "2025-04-02T00:00:00",
+          "categoryId": "adminide-modules"
+        },
         {
           "id": "adminide-modules-preferences-credentials-contribution",
           "title": "Credentials Contribution",
@@ -5529,6 +5559,7 @@
     "adminide-modules-preferences-policy-configuration": "/content/docs/adminide-modules/preferences/Policy-Configuration.md",
     "adminide-modules-preferences-ui-components-resourcesettingsloader": "/content/docs/adminide-modules/preferences/UI-components/ResourceSettingsLoader.md",
     "adminide-modules-preferences-contribute_scope_target": "/content/docs/adminide-modules/preferences/contribute_scope_target.md",
+    "adminide-modules-preferences-contributes-configuration": "/content/docs/adminide-modules/preferences/contributes-configuration.md",
     "adminide-modules-preferences-credentials-contribution": "/content/docs/adminide-modules/preferences/credentials-contribution.md",
     "adminide-modules-preferences-generate-urii": "/content/docs/adminide-modules/preferences/generate-urii.md",
     "adminide-modules-preferences-machine-configuration": "/content/docs/adminide-modules/preferences/machine-configuration.md",
@@ -6153,6 +6184,30 @@
                 "updatedAt": "Recently",
                 "frontmatter": {}
               },
+              {
+                "type": "file",
+                "name": "contributes-configuration",
+                "title": "Contributes Configuration - defaultValueSource",
+                "path": "adminide-modules/preferences/contributes-configuration.md",
+                "contentId": "adminide-modules-preferences-contributes-configuration",
+                "slug": "preferences-contributes-configuration",
+                "categoryId": "adminide-modules",
+                "filePath": "/content/docs/adminide-modules/preferences/contributes-configuration.md",
+                "relativePath": "adminide-modules/preferences/contributes-configuration.md",
+                "description": "How to use defaultValueSource to resolve configuration defaults from vault secrets or environment variables",
+                "author": "Documentation",
+                "updatedAt": "2025-04-02T00:00:00",
+                "frontmatter": {
+                  "meta": "",
+                  "title": "Contributes Configuration - defaultValueSource",
+                  "description": "How to use defaultValueSource to resolve configuration defaults from vault secrets or environment variables",
+                  "date": "2025-04-02T00:00:00",
+                  "updated": "2025-04-02T00:00:00",
+                  "excerpt": "Contributes Configuration - defaultValueSource...",
+                  "headers": "",
+                  "Cache-Control": "no-cache"
+                }
+              },
               {
                 "type": "file",
                 "name": "credentials-contribution",
@@ -10421,6 +10476,12 @@
               "children": [],
               "isFile": true
             },
+            {
+              "title": "Contributes Configuration - defaultValueSource",
+              "path": "/help/adminide-modules/preferences-contributes-configuration",
+              "children": [],
+              "isFile": true
+            },
             {
               "title": "Credentials Contribution",
               "path": "/help/adminide-modules/preferences-credentials-contribution",

package/lib/templates/content/docs/adminide-modules/preferences/contributes-configuration.md

@@ -0,0 +1,332 @@
+---
+meta:
+    title: Contributes Configuration - defaultValueSource
+    description: How to use defaultValueSource to resolve configuration defaults from vault secrets or environment variables
+date: '2025-04-02T00:00:00'
+updated: '2025-04-02T00:00:00'
+excerpt: Contributes Configuration - defaultValueSource...
+headers:
+    Cache-Control: no-cache
+---
+
+# Contributes Configuration — `defaultValueSource`
+
+When defining contributed configuration properties, you can specify a `defaultValueSource` to tell the system **where** the default value should come from at runtime. Instead of hard-coding secrets or environment-specific URLs into configuration defaults, you declare the resolution strategy and the server resolves the actual value when settings are read.
+
+## Configuration Key vs Value Storage
+
+The **configuration key** (e.g. `connector.github.clientSecret`) is defined by the **scope** — the scope determines _where_ the key is visible and at which level it can be set.
+
+The **configuration value** storage depends on `defaultValueSource.type`:
+
+| `defaultValueSource.type` | Value Stored In                                      |
+| ------------------------- | ---------------------------------------------------- |
+| _(not set)_               | Project settings (default — stored in settings JSON) |
+| `environment`             | Resolved from environment variables at read time     |
+| `vault`                   | Stored in / retrieved from the vault system          |
+
+For `WINDOW` (organization) scope without a vault source, the value is stored in **organization settings**.
+
+For `APPLICATION` scope (schemaId `uiLayout`), the value is stored in the **Application collection** under `settings`.
+
+## GraphQL Schema
+
+```graphql
+enum ContributeDefaultValueSourceType {
+    """
+    Resolve from a vault secret (e.g., API keys, OAuth secrets)
+    """
+    vault
+    """
+    Resolve by substituting environment variables in the default value template
+    """
+    environment
+}
+
+type ContributeDefaultValueSource {
+    """
+    The source type for default value resolution
+    """
+    type: ContributeDefaultValueSourceType!
+    """
+    The secret type (e.g., OAUTH_CLIENT, API_KEY). Used when type=vault.
+    """
+    secretType: String
+    """
+    The vault key name (e.g., CONTENTFUL_CLIENT_SECRET). Used when type=vault.
+    """
+    secretKey: String
+    """
+    Whether the secret requires a signature for access. Used when type=vault.
+    """
+    requiredSignature: Boolean
+}
+```
+
+## TypeScript Enum
+
+The generated enum uses PascalCase values:
+
+```ts
+import { ContributeDefaultValueSourceType } from '@adminide-stack/common/server';
+
+ContributeDefaultValueSourceType.Vault; // 'vault'
+ContributeDefaultValueSourceType.Environment; // 'environment'
+```
+
+---
+
+## Type: `vault`
+
+Use `vault` when the configuration property holds a **secret** (API key, OAuth client secret, token, etc.) that should be stored in and retrieved from the vault system.
+
+### How It Works
+
+1. The property must have `format: 'secret'` and `writeOnly: true`.
+2. When the user saves a value, it is stored in the vault (not in the settings JSON).
+3. When settings are read, the server calls `secretResolverService.resolveSecretReference()` to fetch the real value from the vault.
+4. If no vault password/token is provided in the request, the value is masked as `'xxxxx'`.
+
+### Vault Routing by Scope
+
+When `defaultValueSource.type` is `vault`, the scope determines **which vault** the secret is stored in:
+
+| Scope                     | Value | Vault Target             |
+| ------------------------- | ----- | ------------------------ |
+| `APPLICATION` (1)         | 1     | Personal (account) vault |
+| `MACHINE` (2)             | 2     | Personal (account) vault |
+| `RESOURCE` (4)            | 4     | Project vault            |
+| `MACHINE_OVERRIDABLE` (6) | 6     | Provider project vault   |
+
+### Example — Vault Secret
+
+```ts
+addField('apiKey', {
+    type: 'string',
+    title: 'API Key',
+    format: 'secret',
+    default: '',
+    writeOnly: true,
+    scope: ConfigurationScope.MACHINE,
+    defaultValueSource: {
+        type: 'vault',
+        secretType: 'API_KEY',
+        secretKey: 'CONTENTFUL_API_KEY',
+    },
+});
+```
+
+### `defaultValueSource` Fields for Vault
+
+| Field               | Required | Description                                                        |
+| ------------------- | -------- | ------------------------------------------------------------------ |
+| `type`              | Yes      | Must be `'vault'`                                                  |
+| `secretType`        | Yes      | Category: `'OAUTH_CLIENT'`, `'API_KEY'`, `'ENVIRONMENT_VAR'`, etc. |
+| `secretKey`         | Yes      | Key name in the vault, e.g. `'GITHUB_CLIENT_SECRET'`               |
+| `requiredSignature` | No       | If `true`, the secret requires a signature for access              |
+
+### Example — OAuth Client Secret
+
+```ts
+addField('clientSecret', {
+    type: 'string',
+    title: 'Client Secret',
+    format: 'secret',
+    default: '',
+    writeOnly: true,
+    scope: ConfigurationScope.MACHINE,
+    defaultValueSource: {
+        type: 'vault',
+        secretType: 'OAUTH_CLIENT',
+        secretKey: 'GITHUB_CLIENT_SECRET',
+        requiredSignature: true,
+    },
+});
+```
+
+---
+
+## Type: `environment`
+
+Use `environment` when the default value should be **built from environment variables** at runtime. This is useful for URLs and endpoints that differ per deployment (local dev, staging, production) without storing them as secrets.
+
+### How It Works
+
+1. The `default` value is a **template string** using `{{VAR_NAME}}` (Mustache-style double curly braces) as placeholders.
+2. When settings are read, the server replaces each `{{VAR_NAME}}` with the corresponding validated environment variable value.
+3. Only variables listed in the **allowlist** (`allowed-env-variables.ts`) are resolved. Unlisted variables resolve to an empty string and produce a warning log.
+4. The resolution does **not** require the `secretResolverService` — it runs purely from the environment.
+
+### Template Syntax
+
+Use **double curly braces** `{{VAR_NAME}}`:
+
+```
+'{{CLIENT_URL}}/{{CONNECTOR_ENDPOINT}}'
+```
+
+> **Why `{{...}}` instead of `${...}`?**
+> Single-dollar syntax `'${VAR}'` triggers ESLint's [`no-template-curly-in-string`](https://eslint.org/docs/latest/rules/no-template-curly-in-string) rule because it looks like a JavaScript template literal. Double curly braces are a widely recognized convention (Helm, Handlebars, Angular, Jinja2) and avoid this lint error.
+
+### Allowed Environment Variables
+
+Only variables registered in `allowed-env-variables.ts` can be resolved. This prevents leaking sensitive environment variables (e.g. `MONGO_URL`, database credentials) through settings.
+
+```ts
+// packages/adminide-platform/server/src/config/allowed-env-variables.ts
+import { str, cleanEnv } from 'envalid';
+
+export const exposableEnvConfig = cleanEnv(process.env, {
+    CLIENT_URL: str({ default: '', devDefault: 'http://localhost:3000' }),
+    CONNECTOR_ENDPOINT: str({ default: '', devDefault: 'connector-callback' }),
+    APP_URL: str({ default: '', devDefault: 'http://localhost:3000' }),
+    API_URL: str({ default: '', devDefault: 'http://localhost:8080' }),
+    OAUTH_REDIRECT_BASE_URL: str({ default: '', devDefault: 'http://localhost:3000' }),
+});
+
+export const ALLOWED_ENV_VARIABLES: ReadonlySet<string> = new Set(Object.keys(exposableEnvConfig));
+```
+
+Each variable uses [`envalid`](https://github.com/af/envalid) validation with:
+
+- **`default`**: Fallback for production (empty string means the env var must be set in production).
+- **`devDefault`**: Fallback for local development (`NODE_ENV !== 'production'`).
+
+### Adding a New Environment Variable
+
+1. Add the variable to `exposableEnvConfig` in `allowed-env-variables.ts`.
+2. Set the env var in your deployment (`.env`, Helm values, etc.).
+3. Reference it in your configuration property's `default` using `{{VAR_NAME}}`.
+
+### Example — Redirect URI from Environment
+
+```ts
+addField('redirectUri', {
+    type: 'string',
+    title: 'Redirect URI',
+    default: '{{CLIENT_URL}}/{{CONNECTOR_ENDPOINT}}',
+    readOnly: true,
+    scope: ConfigurationScope.MACHINE,
+    defaultValueSource: {
+        type: 'environment',
+    },
+});
+```
+
+At runtime, if `CLIENT_URL=https://app.example.com` and `CONNECTOR_ENDPOINT=connector-callback`, the resolved value is:
+
+```
+https://app.example.com/connector-callback
+```
+
+In local development (no env vars set), `devDefault` values are used:
+
+```
+http://localhost:3000/connector-callback
+```
+
+### `defaultValueSource` Fields for Environment
+
+| Field  | Required | Description             |
+| ------ | -------- | ----------------------- |
+| `type` | Yes      | Must be `'environment'` |
+
+No other fields are needed — the variable names come from the `{{...}}` placeholders in the `default` value.
+
+---
+
+## Resolution Flow
+
+```
+                        ┌──────────────────────┐
+                        │ Read settings for key │
+                        └──────────┬───────────┘
+                                   │
+                        ┌──────────▼───────────┐
+                        │ Has defaultValueSource│
+                        │    on metadata?       │
+                        └──────────┬───────────┘
+                                   │
+                   ┌───────────────┼───────────────┐
+                   │                               │
+          type = environment                type = vault
+                   │                               │
+      ┌────────────▼───────────┐       ┌───────────▼──────────┐
+      │ Replace {{VAR}} with   │       │ Has vault password/  │
+      │ allowlisted env values │       │ token in request?    │
+      └────────────┬───────────┘       └───────────┬──────────┘
+                   │                        Yes    │    No
+                   │                    ┌──────────┼──────────┐
+                   │                    │                      │
+                   │          ┌─────────▼────────┐   ┌────────▼──────┐
+                   │          │ resolveSecret()  │   │ Return xxxxx  │
+                   │          └─────────┬────────┘   └───────────────┘
+                   │                    │
+                   ▼                    ▼
+              Resolved value       Resolved value
+```
+
+---
+
+## Full Example — Mixed Vault and Environment in One Connector
+
+A connector extension typically uses both types together:
+
+```ts
+// Redirect URI — resolved from environment
+addField('redirectUri', {
+    type: 'string',
+    title: 'Redirect URI',
+    default: '{{CLIENT_URL}}/{{CONNECTOR_ENDPOINT}}',
+    readOnly: true,
+    scope: ConfigurationScope.MACHINE,
+    defaultValueSource: { type: 'environment' },
+});
+
+// Client ID — resolved from vault
+addField('clientId', {
+    type: 'string',
+    title: 'Client ID',
+    format: 'secret',
+    default: '',
+    writeOnly: true,
+    scope: ConfigurationScope.MACHINE,
+    defaultValueSource: {
+        type: 'vault',
+        secretType: 'OAUTH_CLIENT',
+        secretKey: 'GITHUB_CLIENT_ID',
+    },
+});
+
+// Client Secret — resolved from vault
+addField('clientSecret', {
+    type: 'string',
+    title: 'Client Secret',
+    format: 'secret',
+    default: '',
+    writeOnly: true,
+    scope: ConfigurationScope.MACHINE,
+    defaultValueSource: {
+        type: 'vault',
+        secretType: 'OAUTH_CLIENT',
+        secretKey: 'GITHUB_CLIENT_SECRET',
+    },
+});
+```
+
+---
+
+## Key Files
+
+| File                                                                               | Purpose                                                              |
+| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `adminide-platform/server/src/config/allowed-env-variables.ts`                     | Allowlist of exposable environment variables with envalid validation |
+| `adminide-platform/server/src/services/preferences/preferences-service.ts`         | `_resolveDefaultValueSourceForConfigKey()` — the resolution logic    |
+| `adminide-platform/server/src/graphql/schema/contribution-settings-schema.graphql` | GraphQL enum and type definitions                                    |
+| `common/src/generated/generated-models.ts`                                         | Generated TypeScript enum `ContributeDefaultValueSourceType`         |
+
+## Security Notes
+
+- **Vault secrets** are never returned in plaintext unless the request includes a valid vault password/token.
+- **Environment variables** are restricted to an explicit allowlist. Sensitive variables like `MONGO_URL`, `JWT_SECRET`, database passwords, etc. are **never** exposed through this mechanism.
+- The allowlist is validated at server startup via `envalid`. Missing required variables in production will cause a startup error.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cdmbase/wiki-browser",
-    "version": "12.0.18-alpha.49",
+    "version": "12.0.18-alpha.50",
     "description": "Sample core for higher packages to depend on",
     "license": "ISC",
     "author": "CDMBase LLC",
@@ -65,7 +65,7 @@
             }
         ]
     },
-    "gitHead": "3c1a1c817bd7a4c486259bba60746627fd9068b8",
+    "gitHead": "ad35818a795169e2e81e6ff6a1248098befbe459",
     "typescript": {
         "definition": "lib/index.d.ts"
     }