@endora-commerce/mod-credentials 0.100.0

package/docs/credentials.md

@@ -0,0 +1,202 @@
+---
+title: Credentials
+description: Reusable typed credential configurations (LLM, email adapter) referenced from settings
+---
+
+# Credentials
+
+The `credentials` module lets an operator define a **reusable
+credential configuration once** and reference it from many places. Instead of
+re-typing an API key into the AI-assistant settings, the search-embedder
+settings, and the newsletter settings, you create a single *Primary LLM*
+configuration and point each setting at it. Change the key once — every
+consumer picks up the new value with no further edits.
+
+Secret fields (API keys, passwords) are **encrypted at rest**, **write-only at
+the boundary** (never returned in plaintext), **masked on every read**, and
+**redacted in the audit log**. Every create / edit / delete is audited through
+the Command Bus.
+
+## For Product Owners & operators
+
+### What a credential configuration is
+
+A configuration is a named, coded instance of a **configuration type**. Two
+types ship out of the box:
+
+- **LLM** — providers **GPT** (OpenAI), **Gemini** (Google), **Claude**
+  (Anthropic), and **DeepSeek**. Fields: **API Key** (secret, required),
+  **Model** (required), **Base URL** (optional).
+- **Email adapter** — providers **SMTP**, **Amazon SES**, and **SendGrid**.
+  Each provider has its own field set with exactly one secret field
+  (SMTP `password`, SES `secretAccessKey`, SendGrid `apiKey`).
+
+The type and provider you pick decide which fields the form shows.
+
+### Creating a configuration
+
+1. Open **Credentials** in the admin sidebar (visible with the
+   `credentials:read` permission).
+2. Click **New configuration**.
+3. Pick a **Type** (e.g. *LLM*) and a **Provider** (e.g. *Claude*). The form
+   redraws to that provider's fields.
+4. Fill in a **Name** (e.g. `Primary LLM`) and a **Code** (a stable identifier
+   like `primary-llm` — this is what settings reference), then the fields
+   (API Key, Model, …).
+5. **Save.** The configuration appears in the list; every secret field shows as
+   **set** — never the value.
+
+Editing works the same way. On edit, the **type and provider are locked** (they
+cannot change — create a new configuration instead). Leaving a secret field
+**blank keeps the stored secret**; typing a new value replaces it.
+
+### Using a configuration from a setting
+
+Some settings are of the **"credential reference"** kind, constrained to one
+configuration type. Such a setting renders as a **picker of matching
+configurations** plus a **Preview** button:
+
+1. Open **Settings** and find the credential-reference setting (e.g. an AI
+   assistant's *LLM credentials*).
+2. Select your configuration from the dropdown — only configurations of the
+   right type are offered.
+3. Click **Preview** to see the referenced configuration read-only (secrets
+   masked) without leaving the page.
+
+Assign the **same** configuration to several settings to reuse it. Update the
+configuration's key once and all of them resolve the new value.
+
+### Safety
+
+- **Delete is blocked while referenced.** Trying to delete a configuration that
+  a setting still points at fails with a clear message listing exactly which
+  settings to detach first.
+- **Orphaned configurations** (whose type is no longer available) are shown
+  read-only ("unavailable") and never crash the screen.
+- **No plaintext ever leaves the server** — list, detail, and preview all mask
+  secrets; only the server-side consumer path decrypts, in memory, for use.
+
+## For developers
+
+### Model
+
+A configuration type is a **code-registered descriptor** (not database rows):
+
+```ts
+interface ConfigurationTypeDescriptor {
+  code: string;            // 'llm' | 'email_adapter' | …
+  label: string;
+  ownerModule: string;
+  providers: ProviderVariant[];
+}
+interface ProviderVariant { code: string; label: string; fields: FieldDefinition[]; }
+interface FieldDefinition {
+  key: string;
+  label: string;
+  kind: 'string' | 'number' | 'boolean' | 'select';
+  required: boolean;
+  secret: boolean;         // secret ⇒ encrypted at rest, masked on read
+  options?: { value: string; label: string }[];
+  placeholder?: string;
+}
+```
+
+A saved configuration stores `typeCode` + `providerCode` + a `values` bag
+(secret fields hold AES-256-GCM envelopes, non-secret fields hold plain
+scalars) in the `credential_configurations` table (`@GlobalEntity`,
+platform-global).
+
+The credentials **core is type-agnostic**: it reads
+a descriptor only to render fields, derive the write-validator, and learn which
+fields are secret. It never branches on a specific `typeCode` / `providerCode` —
+provider meaning lives with the consumer.
+
+### Registering a new type (the extension point)
+
+Register from any module's install path via the process-wide singleton — **no
+change to the credentials core** is required (overlay-safe):
+
+```ts
+import { configurationTypeRegistry } from '@core/modules/credentials/services/registry-singleton.js';
+
+configurationTypeRegistry.register({
+  code: 'sms_gateway',
+  label: 'SMS Gateway',
+  ownerModule: 'my_module',
+  providers: [
+    {
+      code: 'twilio',
+      label: 'Twilio',
+      fields: [
+        { key: 'accountSid', label: 'Account SID', kind: 'string', required: true, secret: false },
+        { key: 'authToken', label: 'Auth Token', kind: 'string', required: true, secret: true },
+      ],
+    },
+  ],
+});
+```
+
+The type immediately appears in the admin type picker (`GET
+/api/v1/admin/credentials/types`) and is creatable.
+
+### The `credential_ref` settings value type
+
+To let a setting reference a configuration, declare it in a module's settings
+manifest:
+
+```ts
+{
+  code: 'prompt_actions.llm_credentials',
+  name: 'LLM credentials',
+  valueType: 'credential_ref',
+  configurationType: 'llm',   // only configurations of this type are selectable
+  defaultValue: '',           // empty ⇒ not configured
+}
+```
+
+`configurationType` is **required** for `credential_ref` settings and forbidden
+otherwise. The stored value is simply the configuration **code**.
+
+### Resolving a reference (consumer side)
+
+Resolution is a **server-side service call** (never an HTTP response) — the one
+path that returns decrypted secrets, for in-memory use only:
+
+```ts
+const code = await settings.get('prompt_actions.llm_credentials'); // → 'primary-llm'
+const cred = code ? await credentials.resolve(code) : { status: 'not_configured' };
+if (cred.status !== 'ok') throw new Error('LLM not configured'); // fail closed
+callProvider(cred.providerCode, cred.values.apiKey, cred.values.model);
+```
+
+`resolve` returns a discriminated result:
+
+- `{ status: 'ok', typeCode, providerCode, values }` — secrets decrypted;
+- `{ status: 'not_configured' }` — the reference is unset/empty;
+- `{ status: 'unavailable', reason: 'missing' | 'inert_type' }` — a deleted
+  code or an unregistered type.
+
+A consumer never receives a foreign configuration and never a plaintext secret
+over the wire.
+
+### Delete integrity
+
+`CredentialsService.delete` first calls
+`SettingsService.listReferencesToConfiguration(code)` (the only channel by which
+credentials reaches settings). A non-empty result blocks the
+delete with `409 CREDENTIAL_IN_USE`, carrying `{ referencedBy: [{ settingCode,
+salesChannelCode? }] }`.
+
+### Secrets & configuration
+
+Secret fields reuse the platform's AES-256-GCM envelope codec keyed by the
+existing **`SETTINGS_SECRET_ENCRYPTION_KEY`** env var — no new secret to
+provision. Writing a secret without the key fails closed
+(`SETTING_SECRET_KEY_MISSING`); boot warns if the key is unset.
+
+### Permissions
+
+- `credentials:read` — view configurations and the type catalogue (secrets
+  masked).
+- `credentials:write` — create / edit / delete configurations, including
+  writing secret fields.

package/i18n/en.json

@@ -0,0 +1,47 @@
+{
+  "actions.openCredentials.label": "Credentials",
+  "actions.openCredentials.description": "Manage reusable credential configurations referenced by settings",
+  "actions.newCredential.label": "New credential configuration",
+  "actions.newCredential.description": "Create a credential configuration for an LLM, email adapter, or other provider",
+  "page.title": "Credentials",
+  "page.subtitle": "Reusable credential configurations referenced by settings.",
+  "page.new": "New configuration",
+  "page.empty": "No credential configurations yet.",
+  "page.edit": "Edit configuration",
+  "page.deleteConfirm": "Delete this configuration? This cannot be undone.",
+  "table.name": "Name",
+  "table.code": "Code",
+  "table.type": "Type",
+  "table.provider": "Provider",
+  "table.actions": "Actions",
+  "action.edit": "Edit",
+  "action.delete": "Delete",
+  "action.preview": "Preview",
+  "action.save": "Save",
+  "action.cancel": "Cancel",
+  "form.name": "Name",
+  "form.code": "Code",
+  "form.type": "Type",
+  "form.provider": "Provider",
+  "form.secretSet": "Saved — leave blank to keep",
+  "form.secretUnset": "Enter a value",
+  "form.inert": "Unavailable — configuration type is no longer registered",
+  "preview.title": "Configuration preview",
+  "preview.secret": "Set (hidden)",
+  "preview.notSet": "Not set",
+  "error.generic": "Something went wrong.",
+  "error.notFound": "Configuration not found.",
+  "error.codeTaken": "That code is already in use.",
+  "error.typeUnknown": "Unknown configuration type or provider.",
+  "error.validationFailed": "Some fields are invalid.",
+  "error.inUse": "Configuration is referenced by one or more settings.",
+  "error.inUseWith": "Cannot delete — referenced by: {settings}. Detach it from those settings first.",
+  "error.typeImmutable": "The type and provider cannot be changed after creation.",
+  "errors.CREDENTIAL_NOT_FOUND": "Configuration not found.",
+  "errors.CREDENTIAL_CODE_TAKEN": "That code is already in use.",
+  "errors.CREDENTIAL_TYPE_UNKNOWN": "Unknown configuration type or provider.",
+  "errors.CREDENTIAL_VALIDATION_FAILED": "Some fields are invalid.",
+  "errors.CREDENTIAL_IN_USE": "Configuration is referenced by one or more settings.",
+  "errors.CREDENTIAL_TYPE_IMMUTABLE": "The type and provider cannot be changed after creation.",
+  "nav.credentials.label": "Credentials"
+}

package/i18n/pl.json

@@ -0,0 +1,47 @@
+{
+  "actions.openCredentials.label": "Poświadczenia",
+  "actions.openCredentials.description": "Zarządzaj konfiguracjami poświadczeń wskazywanymi przez ustawienia",
+  "actions.newCredential.label": "Nowa konfiguracja poświadczeń",
+  "actions.newCredential.description": "Utwórz konfigurację poświadczeń dla LLM, adaptera e-mail lub innego dostawcy",
+  "page.title": "Poświadczenia",
+  "page.subtitle": "Wielokrotnego użytku konfiguracje poświadczeń wskazywane przez ustawienia.",
+  "page.new": "Nowa konfiguracja",
+  "page.empty": "Brak konfiguracji poświadczeń.",
+  "page.edit": "Edytuj konfigurację",
+  "page.deleteConfirm": "Usunąć tę konfigurację? Tej operacji nie można cofnąć.",
+  "table.name": "Nazwa",
+  "table.code": "Kod",
+  "table.type": "Typ",
+  "table.provider": "Dostawca",
+  "table.actions": "Akcje",
+  "action.edit": "Edytuj",
+  "action.delete": "Usuń",
+  "action.preview": "Podgląd",
+  "action.save": "Zapisz",
+  "action.cancel": "Anuluj",
+  "form.name": "Nazwa",
+  "form.code": "Kod",
+  "form.type": "Typ",
+  "form.provider": "Dostawca",
+  "form.secretSet": "Zapisano — pozostaw puste, aby zachować",
+  "form.secretUnset": "Wprowadź wartość",
+  "form.inert": "Niedostępne — typ konfiguracji nie jest już zarejestrowany",
+  "preview.title": "Podgląd konfiguracji",
+  "preview.secret": "Ustawione (ukryte)",
+  "preview.notSet": "Nie ustawiono",
+  "error.generic": "Coś poszło nie tak.",
+  "error.notFound": "Nie znaleziono konfiguracji.",
+  "error.codeTaken": "Ten kod jest już używany.",
+  "error.typeUnknown": "Nieznany typ konfiguracji lub dostawca.",
+  "error.validationFailed": "Niektóre pola są nieprawidłowe.",
+  "error.inUse": "Konfiguracja jest wskazywana przez co najmniej jedno ustawienie.",
+  "error.inUseWith": "Nie można usunąć — wskazywana przez: {settings}. Najpierw odłącz ją od tych ustawień.",
+  "error.typeImmutable": "Nie można zmienić typu i dostawcy po utworzeniu.",
+  "errors.CREDENTIAL_NOT_FOUND": "Nie znaleziono konfiguracji.",
+  "errors.CREDENTIAL_CODE_TAKEN": "Ten kod jest już używany.",
+  "errors.CREDENTIAL_TYPE_UNKNOWN": "Nieznany typ konfiguracji lub dostawca.",
+  "errors.CREDENTIAL_VALIDATION_FAILED": "Niektóre pola są nieprawidłowe.",
+  "errors.CREDENTIAL_IN_USE": "Konfiguracja jest wskazywana przez co najmniej jedno ustawienie.",
+  "errors.CREDENTIAL_TYPE_IMMUTABLE": "Nie można zmienić typu i dostawcy po utworzeniu.",
+  "nav.credentials.label": "Poświadczenia"
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@endora-commerce/mod-credentials",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Reusable credential configurations (LLM, email adapter, …) referenced by settings and resolved by consumers; secrets encrypted at rest and write-only at the boundary.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "credentials"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/credentials"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./admin-ui": {
+      "types": "./dist/admin-ui/index.d.ts",
+      "default": "./dist/admin-ui/index.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs",
+    "tailwind.css"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "react": "^19",
+    "react-router-dom": "^7",
+    "zod": "^4",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "peerDependenciesMeta": {
+    "@endora-commerce/admin-kit": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "@types/react": "^19.2.14",
+    "fastify": "^5.12.5",
+    "react": "^19.2.5",
+    "react-router-dom": "^7.18.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.2.0",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}

package/tailwind.css

@@ -0,0 +1,16 @@
+/* @endora-commerce/mod-credentials — AUTO-GENERATED by `pnpm --filter backend run manifests:generate`.
+ *
+ * The `@source` directives this package asks its host to scan
+ * (`specs/110-instance-repository/contracts/admin-stylesheet-composition.md` R1).
+ * They resolve relative to **this file**, so they hold wherever the package is
+ * installed — a workspace link here, `node_modules` in a client's instance.
+ *
+ * The `dist` line is what a published tarball ships and is what an instance
+ * scans; the `src` line is inert there and is what keeps `pnpm --filter admin
+ * run dev` reading source in this repository. Do not edit: run
+ * `pnpm --filter backend run manifests:generate`.
+ */
+@source "./dist/admin";
+@source "./src/admin";
+@source "./dist/admin-ui";
+@source "./src/admin-ui";