VEYNDO
Handbook
docs/app-settings-service.mdView source ↗

English source · 4 min

Configure an installed App from your own application

Read and update declared installation settings through HTTP, MCP or the existing JavaScript SDK. Secret settings are encrypted in PostgreSQL and never returned. The standalone service runs without Veyndo Core; native Veyndo uses the same settings transaction, projection and original authenticated encryption envelope.

Explicit operator setup

Start with the dedicated reader schema and managed write upgrade. As its original migration owner run:

psql "$APP_DATA_MIGRATION_URL" -X -v reader_role=app_data_reader \
  -f data-service/sql/enable-settings.sql

This upgrades schema 2 to 3. It adds one fixed app_service_secrets table and the native package digest registration column. It expands the existing minimized outbox contract for app.secret_rotated. The serving login can select/insert settings and update ciphertext, digest, revision, actor and rotation time. It cannot change tenant/App/kind keys, delete settings, install packages, read the outbox or create SQL objects. Signed forced RLS remains active. Startup checks reject missing or excessive grants and mismatched profiles. No per-App tables or indexes are created.

The trusted installation owner must validate/provision complete immutable packages and register model::manifest::canonical_digest(&manifest) in app_packages.digest. Existing rows default to an empty registration and cannot save settings until that owner registers their exact current package. A settings request cannot change this column. The separate schema-4 installation profile can review and install portable packages; schema 3 alone cannot.

Set these private deployment values alongside the existing App Data configuration:

Variable Value
APP_DATA_MODE write
APP_DATA_SETTINGS enabled
APP_DATA_SETTINGS_KEY Separate operator key of 64 random hexadecimal characters

Keep the encryption key in the operator's secret manager and backup procedure. Never reuse the signed SQL key. Restart with the same encryption key to read existing configuration. This release provides no key-reencryption endpoint. Disabled settings and read-only profiles never adopt these extra grants silently.

Current personal administrator

Each request performs fresh introspection with the existing fixed OAuth owner. Besides the current merchant/audience/tenant/subject/expiry context, settings need apps.read apps.manage team.manage, personal_session: true and live: true. The identity owner must derive these nondelegatable claims from the actual personal live administrator session, never from scope requests or App input. Missing claims default to false. Machine keys, callback tokens, delegated agents, shoppers and private stages cannot manage these settings. No second role store, issuer, cached consent or browser-supplied identity is introduced.

These are host management operations. Their HTTP and MCP adapters share this administrator admission, independent of per-App data action MCP opt-in. Using MCP never relaxes personal identity or explicit approval requirements.

Read settings

POST /v1/settings/read
Authorization: Bearer <current personal resource access token>
Content-Type: application/json

{"app":"advice"}

The response contains fields with multilingual labels, visible nonsecret values, configured key names, revision, digest, current, canManage and encryptionReady. A secret value, ciphertext or vault key never appears here. Original empty strings, false and zero remain distinct. Older-package values are hidden with current: false; the user must review and supply current settings.

Save an explicit partial update

POST /v1/settings/save
Authorization: Bearer <current personal resource access token>
Content-Type: application/json

{"app":"advice","digest":"<digest from read>","revision":0,"approve":true,
 "values":{"key":"<new private App value>","enabled":false,"limit":0}}

Omitted declared values are preserved only for the same package. Required values cannot be cleared. Unknown keys/types/control characters, oversized payloads, false approval and stale digest/revision reject. Shared encrypted CAS, actor, package lock and metadata-only outbox run in one transaction. A late failure rolls everything back. A conflict returns 409; reload and review before retrying. After a network timeout, read the current revision before retrying an uncertain write. Encryption authenticates tenant, App, kind, package and revision.

Existing SDK and MCP

MCP /mcp advertises apps.settings.read and apps.settings.save only in the enabled settings profile. /v1/contract and /v1/openapi.json expose the same strict wire schemas. The SDK requires no service-specific fork:

await client.initialize();
const settings = await client.tool('apps.settings.read', {app: 'advice'});
await client.tool('apps.settings.save', {
  app: 'advice', digest: settings.digest, revision: settings.revision,
  approve: true, values: {enabled: false}
});

Executable SDK and Fetch example is the actual synthetic fixture workflow. tests/acceptance.py runs the real Rust process and PostgreSQL with two shops, current authority, CAS races, package changes, late rollback, wrong keys, cross-shop ciphertext rejection and persistence across restart. Container CI repeats it using the nonroot Rust-only image. The installation profile is a separate opt-in. Settings alone do not provide transport-secret rotation, jobs, internal runtime setting resolution, restore or complete standalone release orchestration.