@cdmbase/wiki-browser 12.0.18-alpha.45 → 12.0.18-alpha.48

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

@@ -540,6 +540,18 @@
       "updatedAt": "Recently",
       "frontmatter": {}
     },
+    {
+      "contentId": "adminide-modules-preferences-credentials-contribution",
+      "slug": "preferences-credentials-contribution",
+      "filePath": "/content/docs/adminide-modules/preferences/credentials-contribution.md",
+      "relativePath": "adminide-modules/preferences/credentials-contribution.md",
+      "categoryId": "adminide-modules",
+      "title": "Credentials Contribution",
+      "description": "",
+      "author": "Documentation",
+      "updatedAt": "Recently",
+      "frontmatter": {}
+    },
     {
       "contentId": "adminide-modules-preferences-generate-urii",
       "slug": "preferences-generate-urii",
@@ -3865,6 +3877,15 @@
           "updatedAt": "Recently",
           "categoryId": "adminide-modules"
         },
+        {
+          "id": "adminide-modules-preferences-credentials-contribution",
+          "title": "Credentials Contribution",
+          "description": "",
+          "slug": "preferences-credentials-contribution",
+          "author": "Documentation",
+          "updatedAt": "Recently",
+          "categoryId": "adminide-modules"
+        },
         {
           "id": "adminide-modules-account-auth0-login",
           "title": "Facebook Setup",
@@ -5508,6 +5529,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-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",
     "adminide-modules-preferences-pagesettings-generatecdecodeuri": "/content/docs/adminide-modules/preferences/pageSettings/generateCdecodeUri.md",
@@ -6131,6 +6153,21 @@
                 "updatedAt": "Recently",
                 "frontmatter": {}
               },
+              {
+                "type": "file",
+                "name": "credentials-contribution",
+                "title": "Credentials Contribution",
+                "path": "adminide-modules/preferences/credentials-contribution.md",
+                "contentId": "adminide-modules-preferences-credentials-contribution",
+                "slug": "preferences-credentials-contribution",
+                "categoryId": "adminide-modules",
+                "filePath": "/content/docs/adminide-modules/preferences/credentials-contribution.md",
+                "relativePath": "adminide-modules/preferences/credentials-contribution.md",
+                "description": "",
+                "author": "Documentation",
+                "updatedAt": "Recently",
+                "frontmatter": {}
+              },
               {
                 "type": "file",
                 "name": "generate-urii",
@@ -10384,6 +10421,12 @@
               "children": [],
               "isFile": true
             },
+            {
+              "title": "Credentials Contribution",
+              "path": "/help/adminide-modules/preferences-credentials-contribution",
+              "children": [],
+              "isFile": true
+            },
             {
               "title": "Generate URI",
               "path": "/help/adminide-modules/preferences-generate-urii",

package/lib/templates/content/docs/adminide-modules/preferences/credentials-contribution.md

@@ -0,0 +1,692 @@
+# Contributed Credential Fields — Scope-Based Vault Routing
+
+## Summary
+
+Extension-contributed configuration properties with `format: "secret"` and `defaultValueSource.type: "vault"` need to route secrets to the correct vault based on **scope**. User-scoped secrets go to the **personal (account) vault**. Organization/project-scoped secrets go to the **project vault**. Today all secrets are routed to project vaults regardless of scope — this document defines the scope-aware routing design.
+
+---
+
+## Current State
+
+### How Secrets Flow Today
+
+```
+Extension contributes configuration:
+  format: "secret" + defaultValueSource.type: "vault"
+       │
+       ▼
+PreferencesService.writeSettings()
+       │
+       ├── Separates secrets from regular settings (format === 'secret')
+       ├── Extracts projectId from cdecode URI path segments
+       │
+       ▼
+SecretResolverService.storeSecret({ projectId, secretKey, secretValue, secretType })
+       │
+       ▼
+KeyMgmtSecretService.createSecret()  →  Always project-scoped vault
+```
+
+**Problem:** The `scope` value from the contribution schema is ignored during secret storage. An org-scoped secret (scope 3) and a publisher-scoped secret (scope 6) both end up in the same project vault. Additionally, there is no mechanism for users to choose whether a BYOK API key should be stored personally (account vault) or per-project (project vault).
+
+---
+
+## Configuration Scope Values
+
+From `ConfigurationScope` enum:
+
+| Value | Name | Level | Settings Storage | Secret Storage Target |
+|---|---|---|---|---|
+| 1 | `APPLICATION` | User | User settings | **Personal vault** (accountId) |
+| 2 | `MACHINE` | User | User settings | **Personal vault** (accountId) |
+| 3 | `WINDOW` | Organization | Organization settings | **Organization vault** (orgId) or project vault |
+| 4 | `RESOURCE` | Project | Project settings | **Project vault** (projectId) |
+| 5 | `RESOURCE_OVERRIDABLE` | Project | Project settings (overridable) | **Project vault** (projectId) |
+| 6 | `MACHINE_OVERRIDABLE` | Publisher (global) | All orgs/projects can access | **Publisher vault** (shared across orgs) |
+
+### Routing Rule
+
+```
+Scope 1-2 (APPLICATION, MACHINE)           →  Personal vault (account-scoped, user-only)
+Scope 3   (WINDOW)                         →  Organization-level (org settings + org/project vault)
+Scope 4-5 (RESOURCE, RESOURCE_OVERRIDABLE) →  Project vault (project-scoped)
+Scope 6   (MACHINE_OVERRIDABLE)            →  Publisher scope (shared across all orgs/projects)
+```
+
+### Why This Split
+
+- **Scope 1-2** are user-centric — values that follow the user across orgs/projects. Secrets at these scopes are personal credentials (personal API keys, personal OAuth tokens).
+- **Scope 3 (WINDOW)** is organization-level — values scoped to an organization. Non-secret settings are stored in organization settings.
+- **Scope 4-5 (RESOURCE)** are project-level — values tied to a specific project. Non-secret settings are stored in project settings, secrets are stored in the project vault with the `projectId`.
+- **Scope 6 (MACHINE_OVERRIDABLE)** is publisher scope — a temporary designation for credentials that need to be accessible across all organizations and projects (e.g., OAuth client ID/secret provided by the extension publisher).
+
+---
+
+## Contributed Configuration Schema
+
+### Field Structure
+
+```jsonc
+{
+  "contributes": {
+    "configuration": [{
+      "title": "integrationSettings",
+      "properties": {
+        // Publisher-scoped: shared OAuth app credentials (same for all orgs/projects)
+        "integrationSettings.settings.oauth.gmail.oauthConnector.clientId": {
+          "type": "string",
+          "title": "Client ID",
+          "description": "OAuth application client identifier",
+          "default": "",
+          "format": "secret",
+          "defaultValueSource": {
+            "type": "vault",
+            "secretType": "OAUTH_CLIENT",
+            "secretKey": "GMAIL_CLIENT_ID",
+            "requiredSignature": true
+          },
+          "scope": 6                             // MACHINE_OVERRIDABLE = publisher scope
+        },
+        // Project-scoped: user tokens stored per-project in project vault
+        "integrationSettings.settings.oauth.gmail.oauthConnector.accessToken": {
+          "type": "string",
+          "title": "Access Token",
+          "format": "secret",
+          "defaultValueSource": {
+            "type": "vault",
+            "secretType": "OAUTH_CLIENT",
+            "secretKey": "GMAIL_ACCESS_TOKEN"
+          },
+          "scope": 4                             // RESOURCE = project scope
+        },
+        // Project-scoped: non-secret config stored in project settings
+        "integrationSettings.settings.oauth.gmail.oauthConnector.provider": {
+          "type": "string",
+          "title": "Provider",
+          "default": "gmail",
+          "scope": 4                             // RESOURCE = project scope (stored in project settings)
+        }
+      }
+    }]
+  }
+}
+```
+
+### Field Descriptions
+
+| Field | Purpose |
+|---|---|
+| `format: "secret"` | UI hint: mask the value, exclude from regular config store (`bulkWrite`) |
+| `defaultValueSource.type` | Storage backend: `"vault"` routes to vault system |
+| `defaultValueSource.secretType` | Vault item categorization (`OAUTH_CLIENT`, `API_KEY`, `ENVIRONMENT_VAR`, etc.) |
+| `defaultValueSource.secretKey` | The key name used to store/retrieve the secret in the vault |
+| `defaultValueSource.requiredSignature` | Whether the secret requires cryptographic signing before storage |
+| `scope` | **Determines vault routing.** Single number or array. `1-2` → personal, `3` → org, `4-5` → project, `6` → publisher. Array (e.g., `[2, 4]`) = user chooses at write time |
+| `scopePreference` | _(new)_ When `scope` is an array, determines **read priority** — which vault to check first |
+---
+
+## Third-Party API Keys — Multi-Scope Vault Routing (BYOK)
+
+### Problem
+
+The contributed configuration for third-party integrations (Alibaba, Anthropic, OpenAI, AWS, etc.) contains ~100+ API key fields that all currently use `"scope": 3` (WINDOW / organization). These are **Bring Your Own Key (BYOK)** credentials — the user provides their personal API key.
+
+A single fixed scope doesn't work here because the same API key field can legitimately be stored in different places depending on the user's intent:
+
+| Intent | Vault | Reasoning |
+|---|---|---|
+| "This is **my personal** API key, use it everywhere I work" | **Personal vault** (accountId) | Key follows the user across projects/orgs |
+| "This API key is for **this project**, share it with the team" | **Project vault** (projectId) | Key is tied to the project, visible to members with access |
+
+Two users in the same project can each make a different choice — User A stores as shared (project vault), User B stores as personal (personal vault). Both are valid simultaneously.
+
+### Schema Change: `scope` as Array + `scopePreference`
+
+The `scope` field already supports arrays. When a field declares multiple scopes, it means the field can be stored at **any** of those levels and the user chooses which one at write time.
+
+A new `scopePreference` field determines **read priority** — which vault to check first when both personal and project copies might exist:
+
+```jsonc
+"integrationSettings.settings.api.openai.openaiApiKey": {
+  "type": "string",
+  "title": "OpenAI API Key",
+  "default": "",
+  "format": "secret",
+  "defaultValueSource": {
+    "type": "vault",
+    "secretType": "ENVIRONMENT_VAR",
+    "secretKey": "OPEN_AI_API_KEY"
+  },
+  "scope": [2, 4],                              // MACHINE (personal) + RESOURCE (project)
+  "scopePreference": 2,                          // prefer personal vault on read
+  "writeOnly": true
+}
+```
+
+| Field | Type | Purpose |
+|---|---|---|
+| `scope` (array) | `number[]` | Declares all valid storage scopes. `[2, 4]` = personal + project |
+| `scopePreference` | `number` | Which scope to **prefer** on read. Determines vault check order |
+
+### How `scope: [2, 4]` Works
+
+- **Scope 2** (`MACHINE`) = personal / account-level → routes to **personal vault** (accountId)
+- **Scope 4** (`RESOURCE`) = project-level → routes to **project vault** (projectId)
+
+When a field has `scope: [2, 4]`, the UI presents both options and the user picks one:
+
+```
+┌─────────────────────────────────────────────────────┐
+│  OpenAI API Key                                     │
+│  ┌───────────────────────────────────┐              │
+│  │ ●●●●●●●●●●●●●●●●●●●●●●●●         │              │
+│  └───────────────────────────────────┘              │
+│                                                     │
+│  Store as:  ● Personal (my account)                 │
+│             ○ Project (shared with team)             │
+│                                                     │
+│  ℹ️ Personal: follows you across all projects       │
+│     Project: visible to project members with access │
+└─────────────────────────────────────────────────────┘
+```
+
+- **Default selection**: Driven by `scopePreference` value (2 = personal selected by default)
+- The user's choice determines which vault the secret is written to
+- Each user in the same project can independently choose personal or project
+
+### Why `scopePreference` Is Needed
+
+When reading a secret for a field with `scope: [2, 4]`, both a personal and project copy may exist. The system needs to know which to prefer:
+
+| `scopePreference` | Read order | Use case |
+|---|---|---|
+| `2` (personal first) | Personal vault → Project vault | BYOK API keys — user's own key takes priority |
+| `4` (project first) | Project vault → Personal vault | Shared credentials — team key takes priority, personal as fallback |
+
+**Scenario: Two users in the same project**
+
+```
+Project "acme-app" — OpenAI API Key field (scope: [2, 4], scopePreference: 2)
+
+User A: stores as "project" → goes to project vault for acme-app
+User B: stores as "personal" → goes to B's personal vault
+
+When User A reads:  scopePreference=2 → check personal vault (empty) → fallback to project vault ✓
+When User B reads:  scopePreference=2 → check personal vault (found!) → returns B's key
+When User C reads:  scopePreference=2 → check personal vault (empty) → fallback to project vault (User A's shared key) ✓
+```
+
+This means:
+- User B always uses their own personal key (even though a project key exists)
+- Users A and C share the project key
+- No conflicts, no overwrites
+
+### Scope Change for All API Key Fields
+
+All `integrationSettings.settings.api.*` fields currently at `"scope": 3` should be updated:
+
+**Before:** `"scope": 3` → Organization vault (wrong — these are not org-wide credentials)  
+**After (secret fields):** `"scope": [2, 4]` + `"scopePreference": 2` → Personal + project, prefer personal  
+**After (non-secret fields):** `"scope": 4` → Project settings (endpoints, URLs, names)
+
+### Write Flow with Multi-Scope
+
+```typescript
+// In writeSettings(), extract the user's chosen scope from the payload
+const chosenScope = settingsPayload[`${secretKey}.__chosenScope`]; // 2 | 4
+
+function resolveVaultOwnerForMultiScope(
+    scopes: number | number[],
+    chosenScope: number | undefined,
+    context: IUserContext,
+    projectId: string,
+    orgId: string
+) {
+    const scopeArray = Array.isArray(scopes) ? scopes : [scopes];
+
+    // If multi-scope and user explicitly chose, use that scope
+    if (scopeArray.length > 1 && chosenScope && scopeArray.includes(chosenScope)) {
+        return resolveVaultOwner(chosenScope, context, projectId, orgId);
+    }
+
+    // Single scope or no explicit choice — use first scope in array
+    return resolveVaultOwner(scopeArray[0], context, projectId, orgId);
+}
+```
+
+### Read Flow with `scopePreference`
+
+When reading a secret for a multi-scope field, check vaults in `scopePreference` order:
+
+```typescript
+async resolveSecretForMultiScope(params: {
+    secretKey: string;
+    scopes: number | number[];
+    scopePreference: number;
+    accountId: string;
+    projectId: string;
+    orgId: string;
+}) {
+    const { secretKey, scopes, scopePreference, accountId, projectId, orgId } = params;
+    const scopeArray = Array.isArray(scopes) ? scopes : [scopes];
+
+    // Single scope — standard resolution
+    if (scopeArray.length === 1) {
+        const { ownerType, ownerId } = resolveVaultOwner(scopeArray[0], { accountId }, projectId, orgId);
+        return this.resolveSecret({ ownerType, ownerId, secretKey });
+    }
+
+    // Multi-scope: order by scopePreference first, then remaining scopes
+    const orderedScopes = [
+        scopePreference,
+        ...scopeArray.filter(s => s !== scopePreference)
+    ];
+
+    for (const scope of orderedScopes) {
+        const { ownerType, ownerId } = resolveVaultOwner(scope, { accountId }, projectId, orgId);
+        const secret = await this.resolveSecret({ ownerType, ownerId, secretKey });
+        if (secret) {
+            return { ...secret, resolvedFromScope: scope };
+        }
+    }
+
+    return null; // Not stored in any vault
+}
+```
+
+**Resolution order for `scope: [2, 4]` with `scopePreference: 2`:**
+1. Check personal vault (scope 2) → if found, return it
+2. Check project vault (scope 4) → if found, return it
+3. Return null
+
+### Affected Fields
+
+All `integrationSettings.settings.api.*` fields with `format: "secret"` and `scope: 3` should be updated:
+
+| Change | Count | Details |
+|---|---|---|
+| `"scope": 3` → `"scope": [2, 4]` | ~80 secret fields | Personal + project vault |
+| Add `"scopePreference": 2` | ~80 secret fields | Prefer personal vault on read |
+| Non-secret fields `"scope": 3` → `"scope": 4` | ~40 config fields | Endpoints, URLs, names — project settings only |
+
+**Examples of affected providers:** Alibaba, Anthropic, Apify, Arize, AssemblyAI, Astra DB, AWS, Azure OpenAI, Baidu Qianfan, Brave Search, Cerebras, Chroma, Cohere, Composio, Confluence, Couchbase, DeepSeek, DynamoDB, E2B, ElasticSearch, Exa Search, Figma, FireCrawl, Fireworks, GitHub, Google (Custom Search, Generative AI, Vertex AI), Groq, HuggingFace, IBM Watsonx, Jina AI, Langfuse, Langsmith, LangWatch, LocalAI, Lunary, Meilisearch, Milvus, Mistral AI, Momento, MongoDB, MySQL, Neo4j, Notion, NVIDIA NIM, OpenAI, OpenRouter, OpenSearch, Phoenix, Pinecone, PostgreSQL, Qdrant, Redis, Replicate, SearchAPI, SerpApi, Serper, SingleStore, Slack, Spider, Stripe, Supabase, Tavily, Together AI, Unstructured, Upstash (Redis, Vector), Vectara, Voyage AI, Weaviate, Wolfram Alpha, xAI, Zep.
+
+### Example: Updated Field
+
+```jsonc
+// BEFORE
+"integrationSettings.settings.api.openai.openaiApiKey": {
+  "type": "string",
+  "title": "OpenAI API Key",
+  "default": "",
+  "format": "secret",
+  "defaultValueSource": {
+    "type": "vault",
+    "secretType": "ENVIRONMENT_VAR",
+    "secretKey": "OPEN_AI_API_KEY"
+  },
+  "scope": 3,          // WINDOW (org) — wrong
+  "writeOnly": true
+}
+
+// AFTER
+"integrationSettings.settings.api.openai.openaiApiKey": {
+  "type": "string",
+  "title": "OpenAI API Key",
+  "default": "",
+  "format": "secret",
+  "defaultValueSource": {
+    "type": "vault",
+    "secretType": "ENVIRONMENT_VAR",
+    "secretKey": "OPEN_AI_API_KEY"
+  },
+  "scope": [2, 4],          // MACHINE (personal) + RESOURCE (project)
+  "scopePreference": 2,     // prefer personal vault on read
+  "writeOnly": true
+}
+```
+
+---
+
+## Design: Scope-Aware Secret Routing
+
+### Updated Flow
+
+```
+Extension contributes configuration:
+  format: "secret" + defaultValueSource.type: "vault" + scope
+       │
+       ▼
+PreferencesService.writeSettings()
+       │
+       ├── Separates secrets from regular settings
+       ├── Extracts scope from schemaInfo per key
+       │
+       ▼
+  ┌── scope 1-2? ──┬── scope 3? ──────┬── scope 4-5? ─────┬── scope 6? ──────────┐
+  │                 │                  │                    │                      │
+  ▼                 ▼                  ▼                    ▼                      │
+storeSecret({    storeSecret({      storeSecret({        storeSecret({            │
+ ownerType:       ownerType:         ownerType:           ownerType:              │
+  'account',       'organization',    'project',           'publisher',           │
+ ownerId:         ownerId:           ownerId:             ownerId:                │
+  accountId        orgId              projectId            publisherId            │
+})               })                 })                   })                       │
+  │                 │                  │                    │                      │
+  ▼                 ▼                  ▼                    ▼                      │
+Personal vault   Org vault          Project vault        Publisher vault          │
+(user-only)      (org settings)     (per-project)        (shared globally)        │
+```
+
+### Changes Required
+
+#### 1. `_validateSettingsBeforeWrite` — Return Scope in `schemaInfo`
+
+Currently returns `{ format, defaultValueSource }` per key. Add `scope`:
+
+```typescript
+// schemaInfo[key] shape — BEFORE
+{ format?: string; defaultValueSource?: object }
+
+// schemaInfo[key] shape — AFTER
+{ format?: string; defaultValueSource?: object; scope?: number }
+```
+
+Extract `scope` from the schema node alongside `format` and `defaultValueSource`.
+
+#### 2. `writeSettings` — Pass Scope to `storeSecret`
+
+```typescript
+// Current code
+const result = await this.secretResolverService.storeSecret({
+    projectId,
+    secretKey: vaultKeyName,
+    secretValue,
+    secretType: secretTypeValue,
+    environmentTag,
+});
+
+// Updated code — scope-aware routing
+const secretScope = schemaInfo[secretKey]?.scope;
+
+function resolveVaultOwner(scope: number, context: IUserContext, projectId: string, orgId: string) {
+    switch (true) {
+        case scope <= ConfigurationScope.MACHINE: // 1-2: user-only
+            return { ownerType: 'account' as const, ownerId: context.accountId };
+        case scope === ConfigurationScope.WINDOW:  // 3: organization
+            return { ownerType: 'organization' as const, ownerId: orgId };
+        case scope <= ConfigurationScope.RESOURCE_OVERRIDABLE: // 4-5: project
+            return { ownerType: 'project' as const, ownerId: projectId };
+        case scope === ConfigurationScope.MACHINE_OVERRIDABLE: // 6: publisher (global)
+            return { ownerType: 'publisher' as const, ownerId: 'global' };
+        default:
+            return { ownerType: 'project' as const, ownerId: projectId }; // safe default
+    }
+}
+
+const { ownerType, ownerId } = resolveVaultOwner(secretScope, context, projectId, orgId);
+
+const result = await this.secretResolverService.storeSecret({
+    ownerType,
+    ownerId,
+    secretKey: vaultKeyName,
+    secretValue,
+    secretType: secretTypeValue,
+    environmentTag,
+});
+```
+
+#### 3. `ISecretResolverService.storeSecret` — Accept Owner Context
+
+```typescript
+// Current signature
+storeSecret(params: {
+    projectId: string;
+    secretKey: string;
+    secretValue: string;
+    secretType: string;
+    environmentTag?: string;
+}): Promise<{ success: boolean; error?: string }>;
+
+// Updated signature
+storeSecret(params: {
+    ownerType: 'account' | 'organization' | 'project' | 'publisher';  // NEW
+    ownerId: string;                      // NEW (replaces projectId)
+    projectId?: string;                   // DEPRECATED — kept for backward compat
+    secretKey: string;
+    secretValue: string;
+    secretType: string;
+    environmentTag?: string;
+}): Promise<{ success: boolean; error?: string }>;
+```
+
+#### 4. `SecretResolverService.storeSecret` — Route to Correct Vault
+
+```typescript
+async storeSecret(params) {
+    const { ownerType, ownerId, projectId, secretKey, secretValue, secretType, environmentTag } = params;
+
+    // Backward compat: if ownerType not provided, default to project
+    const resolvedOwnerType = ownerType || 'project';
+    const resolvedOwnerId = ownerId || projectId;
+
+    let vault;
+    switch (resolvedOwnerType) {
+        case 'account':
+            // Personal vault — lazy creation
+            vault = await this.vaultService.getOrCreatePersonalVault(resolvedOwnerId);
+            break;
+        case 'organization':
+            // Org vault — lazy creation
+            vault = await this.vaultService.getOrCreateOrgVault(resolvedOwnerId);
+            break;
+        case 'publisher':
+            // Publisher vault — global, shared across all orgs/projects
+            vault = await this.vaultService.getOrCreatePublisherVault(resolvedOwnerId);
+            break;
+        case 'project':
+        default:
+            // Project vault — existing behavior
+            vault = await this.vaultService.getVault(resolvedOwnerId);
+            break;
+    }
+
+    return this.keyMgmtSecretService.createSecret({
+        vaultId: vault.id,
+        secretKey,
+        secretValue,
+        secretType,
+        environmentTag,
+    });
+}
+```
+
+#### 5. `readSecret` — Same Scope-Based Resolution
+
+The read path must mirror the write path. When resolving a `defaultValueSource` secret for display:
+
+```typescript
+async resolveSecret(params) {
+    const { ownerType, ownerId, secretKey } = params;
+
+    let vault;
+    switch (ownerType) {
+        case 'account':
+            vault = await this.vaultService.getPersonalVault(ownerId);
+            break;
+        case 'organization':
+            vault = await this.vaultService.getOrgVault(ownerId);
+            break;
+        case 'publisher':
+            vault = await this.vaultService.getPublisherVault(ownerId);
+            break;
+        case 'project':
+        default:
+            vault = await this.vaultService.getVault(ownerId);
+            break;
+    }
+
+    if (!vault) return null; // Vault not created yet — secret not stored
+    return this.keyMgmtSecretService.getSecret(vault.id, secretKey);
+}
+```
+
+---
+
+## Example: Gmail OAuth Connector Contributed Fields
+
+Given the contribution from the user's example, fields should be scoped as follows:
+
+### Publisher-Scoped (scope 6 — MACHINE_OVERRIDABLE)
+
+Shared across all organizations and projects. These are the extension publisher's OAuth app credentials:
+
+| Property | Scope | Storage | Reasoning |
+|---|---|---|---|
+| `clientId` | 6 | **Publisher vault** (shared) | OAuth app credential provided by publisher — same for all orgs/projects |
+| `clientSecret` | 6 | **Publisher vault** (shared) | OAuth app secret provided by publisher — same for all orgs/projects |
+
+### Project-Scoped (scope 4 — RESOURCE)
+
+Per-project settings and secrets. Non-secret settings go to project settings, secrets go to the project vault with `projectId`:
+
+| Property | Scope | Storage | Reasoning |
+|---|---|---|---|
+| `apiKey` | 4 | **Project vault** (projectId) | API key used within a specific project context |
+| `accessToken` | 4 | **Project vault** (projectId) | User's OAuth access token for this project |
+| `refreshToken` | 4 | **Project vault** (projectId) | User's OAuth refresh token for this project |
+| `provider` | 4 | **Project settings** (not secret) | Configuration value — stored in project settings |
+| `providerTitle` | 4 | **Project settings** (not secret) | Display name — stored in project settings |
+| `redirectUri` | 4 | **Project settings** (not secret) | Callback URL — stored in project settings |
+| `scopes` | 4 | **Project settings** (not secret) | OAuth scopes list — stored in project settings |
+| `description` | 4 | **Project settings** (not secret) | Display text — stored in project settings |
+| `isConnected` | 4 | **Project settings** (not secret) | Connection state — stored in project settings |
+
+### Scope Change Required
+
+The original contribution uses `scope: 3` (WINDOW/Organization) for project-level fields. These should be changed to `scope: 4` (RESOURCE/Project) because:
+- Non-secret settings (provider, redirectUri, scopes, etc.) are stored in **project settings**
+- Secret values (accessToken, refreshToken, apiKey) are stored in the **project vault** with `projectId`
+- WINDOW (3) is organization-level — these values are not org-wide, they are project-specific
+
+This correctly separates:
+- **Publisher credentials** (clientId/clientSecret at scope 6) — provided by the extension publisher, shared globally across all orgs and projects
+- **Project secrets** (accessToken/refreshToken/apiKey at scope 4) — stored per-project in the project vault
+- **Project config** (provider/redirectUri/scopes at scope 4) — stored per-project in project settings
+
+> **Note:** OAuth connector fields use **fixed single scopes** (publisher vs project). They do NOT use multi-scope arrays because the routing is deterministic — publisher credentials are always scope 6 (shared), user tokens are always scope 4 (project-scoped). Multi-scope `[2, 4]` is only for BYOK API key fields where the user decides personal vs shared.
+
+---
+
+## Access Control During Read
+
+When a user reads settings, secrets are resolved from the appropriate vault based on scope:
+
+```
+User opens settings page
+       │
+       ▼
+PreferencesService.readSettings()
+       │
+       ├── Regular settings: read from config store (filtered by scope + target)
+       │
+       ├── Secret settings (format: "secret"):
+       │     │
+       │     ├── scope 1-2? → resolveSecret(ownerType: 'account', ownerId: accountId)
+       │     │                  Returns value ONLY if accountId matches requesting user
+       │     │
+       │     ├── scope 3?   → resolveSecret(ownerType: 'organization', ownerId: orgId)
+       │     │                  Returns value based on org role permissions
+       │     │
+       │     ├── scope 4-5? → resolveSecret(ownerType: 'project', ownerId: projectId)
+       │     │                  Returns value based on project role permissions
+       │     │
+       │     └── scope 6?   → resolveSecret(ownerType: 'publisher', ownerId: publisherId)
+       │                        Returns value (read-only, provided by publisher)
+       │
+       ▼
+Merged settings response (secrets masked in UI)
+```
+
+### Security Rules
+
+| Scenario | Allowed? |
+|---|---|
+| User reads their own personal vault secret (scope 1-2) | Yes |
+| User reads another user's personal vault secret | **No** — account vault is owner-only |
+| Org admin reads org vault secret (scope 3) | Yes |
+| Org member reads org vault secret (scope 3) | Based on org role |
+| Project admin reads project vault secret (scope 4-5) | Yes |
+| Project member (read role) reads project vault secret (scope 4-5) | Yes (value displayed masked) |
+| Any user reads publisher vault secret (scope 6) | Yes (read-only, set by publisher) |
+| Org admin reads a user's personal vault secret | **No** — personal vault is never org-visible |
+
+---
+
+## `requiredSignature` Field
+
+Some secrets require cryptographic signing (e.g., `clientId` and `clientSecret` with `requiredSignature: true`):
+
+```json
+"defaultValueSource": {
+    "type": "vault",
+    "secretType": "OAUTH_CLIENT",
+    "secretKey": "GMAIL_CLIENT_ID",
+    "requiredSignature": true
+}
+```
+
+When `requiredSignature: true`:
+1. Before storing, the secret value is signed using the vault's encryption key
+2. The signature is stored alongside the encrypted value as metadata
+3. On retrieval, the signature is verified to detect tampering
+4. If verification fails, the secret is treated as invalid and the user is prompted to re-enter
+
+This is independent of scope routing — it applies to both personal and project vaults.
+
+---
+
+## Migration Path
+
+### Existing Secrets
+
+Existing secrets are all stored in project vaults. After implementing scope-aware routing:
+
+1. **New secrets** written through `writeSettings` will be routed correctly based on scope
+2. **Existing user-scoped secrets** (scope 1-3) that were stored in project vaults need migration:
+   - Run a migration that reads each secret's schema to determine its scope
+   - For scope 1-3 secrets, move them from project vault to the user's personal vault
+   - This requires knowing which user created the secret (audit trail)
+3. **Existing project-scoped secrets** (scope 4-6) stay where they are — no change needed
+
+### Backward Compatibility
+
+- `storeSecret({ projectId })` without `ownerType` continues to work (defaults to `'project'`)
+- Extensions that don't set `scope` default to project vault (safe default)
+- Read path checks both vaults as fallback during migration period
+
+---
+
+## Files to Change
+
+| File | Change |
+|---|---|
+| `packages/adminide-platform/server/src/services/preferences/preferences-service.ts` | `_validateSettingsBeforeWrite`: return `scope` (may be array) + `scopePreference` in schemaInfo. `writeSettings`: resolve `chosenScope` from payload, pass `ownerType`/`ownerId` |
+| `packages/common/src/services/SecretResolverService.ts` | Update `storeSecret` interface to accept `ownerType` + `ownerId`. Add `resolveSecretForMultiScope` for BYOK fields |
+| `packages-modules/user-auth0/server/src/modules/key-management/services/SecretResolverService.ts` | Implement vault routing based on `ownerType`. Implement multi-vault resolution with `scopePreference` ordering |
+| `packages-modules/user-auth0/server/src/modules/key-management/services/KeyMgmtVaultService.ts` | Use `getOrCreatePersonalVault` for account-scoped secrets (depends on account vault feature from issue #3838) |
+| `packages/credentials/server/src/migrations/...` | Update all `integrationSettings.settings.api.*` secret fields: `scope: 3` → `scope: [2, 4]`, add `scopePreference: 2`. Non-secret fields: `scope: 3` → `scope: 4` |
+
+---
+
+## Dependency
+
+This design depends on **[#3838 — Account-level personal vault support](https://github.com/CDEBase/adminIde-stack/issues/3838)** being implemented first. The personal vault (`getOrCreatePersonalVault`) must exist before user-scoped secrets can be routed there.
+
+Implementation order:
+1. Account-level vault support (#3838)
+2. Scope-aware routing in `writeSettings` / `storeSecret` — support `scope` as `number | number[]`
+3. Multi-scope support — UI toggle for `scope: [2, 4]` fields, `scopePreference` read ordering
+4. Migration: update all `integrationSettings.settings.api.*` secret fields from `scope: 3` → `scope: [2, 4]` + add `scopePreference: 2`. Non-secret fields from `scope: 3` → `scope: 4`
+5. Read-path resolution with `scopePreference` ordering for multi-scope fields
+6. Migration of existing user-scoped secrets from project vaults to personal vaults

package/package.json

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