meinKontextDocs
Navigation & search

Plugin SDK

Credentials & external effects

Encrypted payloads, credential bindings, OAuth handoffs and reviewed provider calls.

SDK 0.1 · ExperimentalMarkdown

This optional Host API 0.1 extension supports reviewed plugins that store encrypted payloads or call external services. Existing document plugins need no new methods. A host without protected-payloads.v1 or external-effects.v1 rejects manifests requiring those capabilities.

The browser-only functions below (confidential, external, authorization, executeConfigured, confidentialStorage, authorizedClients) are optional members of ProcedureContext: a change needs a confidential POST procedure, a function needs its manifest capability, and each call is limited to the procedure's own plugin (API reference). The old stack's PluginRequestContext, which carried the same functions with an owner argument, was removed with the old React Router app (AV07-S04); their semantics are unchanged.

Boundaries

The domain runtime owns metadata, commands, permissions, provider schemas and UI. The generic host owns current authorization, ciphertext persistence, credential bindings, one-use OAuth handoffs and durable effects. The confidential executor owns encryption and provider HTTP requests. It can run as a module inside each trusted backend (embedded) or through the authenticated standalone service (remote). Neither mode is a model-facing capability or an untrusted plugin sandbox. Plugin MCP handlers receive a frozen public host facade: confidential input, export, OAuth handoff and approval methods are absent at runtime, not merely omitted from TypeScript types.

This is encryption at rest. The trusted backend can decrypt authorized credentials. A compromised authorized host or operator can request their use and encrypted export with a chosen passphrase; neither mode promises credential secrecy from that host or the operator. Remote mode isolates key files and process memory, but is not independent user authorization. MCP delivers authorized provider results, never raw provider credentials. Incoming MCP bearer tokens never become upstream authorization headers.

Embedded mode shares one persistent keyring and reviewed provider configuration between the existing web and machine-server processes. No extra listener, RPC authentication key or replay-ledger login is needed. The shared validated facade retains input checks, safe errors and admission bounds per process. Host policy, OAuth one-use checks, refresh leases and durable dispatch fencing stay in the database and apply across processes. Keys never enter the database, public plugin documents or browser build. Files are not hot-reloaded; coordinate process restarts when keys or provider configuration change. See the mode and pilot configuration.

Protected payload contributions

A runtime declares protectedPayload(document) with purpose, generation, status and optional expiry, plus protectedManagePermission and protectedExportPermission. Its public files and projections contain only metadata. A browser action calls the optional ProcedureContext.confidential.commit with a deterministic metadata command, transient value and expected generation.

The host validates custody and live rights before sealing, then atomically commits metadata and ciphertext. Only the host can issue DomainExecutionContext.protectedPayload; a model-supplied field is not a receipt. New or changed generations without the receipt fail. Same-key retries require the same encrypted value, checked inside the executor. Replacing credentials invalidates old bindings; refresh updates an encrypted token set under a persistent lease without changing the user's generation. Revocation retires ciphertext and bindings in the same transaction.

confidential.exportEncrypted is a trusted form-only operation. The executor returns a passphrase-encrypted archive; normal collection exports contain metadata only. confidential.exportEncryptedMany packs several payloads with their record data into one archive of the same format (meinkontext.secret-export v1; plaintext { entries: [{ resourceId, record, value }] }), with the same custody/export checks per resource.

A manifest format may set browserOnly: true: the host's read gate then hides its records from every MCP caller (also the signed-in person's own client), managed service, organization credential and read grant — query, get, commands and search alike — while the trusted browser keeps full access. Secrets marks its vault items so; agent credentials stay listable as metadata.

The only plaintext getter is confidential.reveal (VAULT-PLAN, operator 2026-10-27): a trusted form-only POST that returns the plaintext of a payload sealed with the generic purpose revealable-secret (REVEALABLE_PURPOSE) to the collection custodian holding the plugin's protectedRevealPermission for that record's format. Every reveal writes plugin.protected.revealed to the audit log before the executor opens the envelope. The executor refuses every other purpose, so agent credentials (credential), operations and results stay write-only; no MCP tool, managed service actor or restricted grant reaches reveal. Protected permissions (protectedManagePermission, protectedExportPermission, protectedRevealPermission) take one permission id or one per format id, because the host checks a permission against the record's own format. Keep confidential form fields out of action data, HTML defaults, logs and URLs; a revealed value is returned only in the fetcher reply that asked for it. All forms require same-origin POST; downloads use Cache-Control: no-store.

Behind a TLS-terminating gateway, trusted browser mutations and OAuth setup use the configured public SERVER_ORIGIN, normalized to its origin. If unset, they use the request origin. Forwarded headers never supply this authority. Deployments with aliases must use the configured canonical URL for these confidential actions; the ordinary account page's host check does not add OAuth redirect origins.

Procedures also receive confidentialStorage?.configured: a configuration hint, not a health check or access grant. Absence means unavailable. Disable confidential inputs when it is false and explain that the operator must set up encrypted storage. Keep metadata operations available. A configured executor can still fail at request time; handle that separately without exposing raw errors or submitted values. The hint carries no endpoint, keys or write controls; confidential is present only on confidential POST procedures and absent from read procedures and the public MCP host.

External contributions

A runtime contributes deterministic externalDestination, externalOperation and externalTools hooks. externalOperation returns a reviewed adapter/version, exact destination, mode, approved schema digest and validated input. The host derives actor, owner, policy epoch and credential binding. The caller supplies a resource, operation, arguments and idempotency key through host.external.invoke.

Bindings require the same custodian on both collection roots, a compatible optional integration and current credential management rights. Use-only access to a connection does not grant metadata or export access to its credential. The binding includes the original organization-member incarnation: removal and rejoining cannot revive it. Every dispatch and cached response rechecks current resource rights, protected parents, installation state, versions, schema digest and credential generation.

external.describe returns safe connection readiness and tools under read authority. It does not fetch a token. Invocation needs the separately declared externalPermission. Plugins can degrade when their credential provider is absent; unauthenticated connections remain possible.

Review and replay

Read calls may dispatch after admission. A write first returns pending-review with a browser review URL. ProcedureContext.external.review reads the encrypted original request for the same actor. reviewAndInvoke is available only through a trusted same-origin form; there is no MCP approval method. The review binds exact payload, connection, destination, schema, policy and credential generation. Review links carry the owning organization. Equivalent JSON object key order is ignored for idempotency; array order and changed values still conflict. The browser displays the durable effect status, never an arbitrary provider-supplied success label.

An effect is persisted before network I/O. Its dispatch marker is durable; a timeout or crash after that marker never authorizes a second write. Success caches an encrypted result, with live authorization checked before replay. Definite provider rejections report failure; ambiguous writes report outcome-unknown. Reconcile with the provider before creating a new operation. This is not an exactly-once guarantee across the network.

On status, review or replay, a dispatch marker older than two minutes is conservatively recovered to outcome-unknown for writes and failed for reads. The original dispatch fence remains; neither recovery nor a late response can authorize a second dispatch. A definitive authentication rejection marks only the still-current credential binding and encrypted token version as requiring reauthorization. A stale response cannot invalidate a replacement credential.

Sensitive operation inputs and results stay encrypted in the database. Audit events carry action names, resource/effect IDs and authenticated caller metadata, never credentials or provider payloads. Concurrent refresh callers wait briefly for the existing lease; a lost refresh response requires reauthorization rather than reusing a possibly invalidated refresh token.

The trusted host supplies ExternalCaller with the browser/MCP/controller surface and, for verified OAuth MCP callers, the client ID. A runtime may implement externalAuthorize(document, caller) to restrict use per connection. The host calls it before describing, dispatching, reading status or replaying an external effect. User-wide effect identities do not bypass current client policy. Caller identity never comes from model arguments or an unverified request header.

OAuth handoffs

A runtime declares externalAuthorization, its callback path, and a provider credential kind. The credential plugin contributes createProtectedCommand; the host never inspects domain command discriminators. authorization.start validates browser identity, custody and both installed plugin versions, then stores hashed state plus an encrypted PKCE/private flow. authorization.complete is one-use, actor/member-bound and repeats the exact admission snapshot. It creates the protected credential and binds the connection atomically.

OAuth routes declare both authorizationCallback: true and confidentialQuery: true. Before checking installation, the trusted web dispatcher resolves the owner from the state hash, authenticated actor, current membership, plugin and registered callback path. It never accepts the callback's owner query as routing authority. Completion returns the trusted organizationId for the connection redirect and repeats live admission checks. These lookup methods are absent from the public plugin host.

The optional OAuth callback issuer is passed unchanged to the adapter for RFC 9207 validation against its sealed flow. An adapter needing discovered public authorization hosts explicitly opts into authorizationNetwork: "public-https". This reviewed capability applies only to authorization and refresh: ordinary execution remains destination-bound. Every network hop still passes public-address validation and DNS pinning, rejects redirects, and obeys transport limits. Authorization destinations are validated before browser redirection as well. Discovered issuer, resource and token endpoints belong inside the encrypted flow and credential; refreshing must not rediscover a replacement destination.

Starting or completing a flow clears at most 100 expired encrypted verifiers for the caller and organization, in a separate committed cleanup step. Expired handoffs cannot retain quota merely because the next sign-in or completion fails. Active flows remain untouched; this is lazy cleanup during authorization use, not a background expiry worker.

Provider application configuration belongs to the executor. Access and refresh tokens never enter the ordinary sign-in account table. Failed or stale callbacks cannot create an unbound secret. Redirect query strings, body fields and headers must not appear in application or ingress logs.

Reviewed packages may declare executorConfiguration in the deployment catalog, exporting an ExecutorConfigurationProvider from ./executor-configuration. This private bootstrap contribution owns its adapter IDs, reads only the explicitly supplied environment, and validates its configuration subset without I/O. The executor registry rejects duplicate claims and unknown adapter IDs and replaces validation errors with a fixed code. It is absent from browser/server catalogs, the public host facade, and builds that exclude that package. Secret persistence, deployment admission and keyring isolation remain platform responsibilities.

Dynamic MCP tools

A runtime may return dynamicTools(context). Each contribution supplies its actual input JSON Schema and a stable namespaced name, plus a handler that resolves live authority on every call. resultFormat: "mcp" preserves validated text, images, resource links, structured content and errors rather than wrapping a tool result inside a JSON text result. The ordinary static tools remain available for clients that cache tool lists; reconnect after changing the approved catalog.

Remote descriptions, annotations and outputs are untrusted data. They never enter trusted initialize instructions. Review assigns each remote tool's read/write mode. A changed schema digest blocks old approval. Remote schema policy bounds parsing/expansion and rejects unsafe unsupported constructs; a provider schema cannot monopolize the host event loop. Executor HTTP validates actual DNS/socket destinations, blocks private targets by default and does not forward credentials across redirects.

Adoption and operations

The new plugins deliberately do not declare managed-service adoption. Existing restricted import grants and context-read grants do not acquire external authority. Adding service access requires explicit adoption and separate acceptance under Agent access.

See executor deployment, key rotation, Secrets, Integrations, and the acceptance ledger. Provider consent and native-client interoperability require real acceptance; mocked provider tests do not establish them.

Private configuration during execution

Reviewed adapters receive a frozen copy of their own private backend configuration in execute, as they already do during authorization/refresh. The adapter ID comes from the sealed operation and registered adapter; caller arguments cannot select a different configuration. Configuration never enters operation envelopes. Execution remains restricted to the operation destination. The executor rejects results echoing configured secret/token/private-key fields, including escaped multiline values; this is defense in depth, not a sandbox for untrusted adapter code. Adapters must not return generated credentials or raw provider errors.

Prior-effect evidence and review details

A runtime may declare externalPrerequisites(document, operation, input) as keys of earlier successful effects. The host resolves them only within the current organization, connection and acting principal (including the managed work session). It decrypts operation/result envelopes outside the transaction and rechecks the same rows, success status and envelope bytes at every admission. Missing, erased, failed, ambiguous or foreign receipts deny execution. The runtime must validate what the receipt proves; merely naming a prior key does not authorize a target.

externalOperation receives the trusted actor, current request key and these receipts. Inputs supplied by the model cannot replace that context. Owner review continues to run as the original service/session. Optional reviewDetails are sealed display data for the trusted browser, while reviewInput remains the exact original invocation input for replay. Display details never become execution arguments or appear in ordinary audit records.

Sharing a provider authorization between connections

Trusted browser control may call external.bindFrom with source and target resource IDs. The host requires human custody of both resources, a usable source binding, and the same adapter ID/version and destination. It copies only the binding; the browser receives neither credential ID nor plaintext. Refresh and revocation consequently apply to the one protected credential.

external.unbindShared removes every use of that credential issued by the same human in the organization, including disabled/archived connections, and advances the affected policy epochs. It still works after credential expiry. It does not uninstall a provider App or delete remote data. Both methods are absent from the public MCP host facade and require the existing same-origin trusted form path.

managedExternalPresets is optional plugin-authored UI data. Its operation rows populate the ordinary per-connection policy form; they neither save automatically nor confer authority. Unknown operations remain denied, and issued credential ceilings still require explicit renewal for additional access.