# Confidential payloads and external effects

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](API.md#protected-host-functions)). 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](../../../deploy/executor/README.md).

## 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](AGENT-ACCESS.md).

See [executor deployment](../../../deploy/executor/README.md), [key rotation](../../../docs/plugins/PROTECTED-KEY-ROTATION.md), [Secrets](../../plugin-secrets/GUIDE.md), [Integrations](../../plugin-integrations/GUIDE.md), and the [acceptance ledger](../../../.ytstack/research/2026-10-14-secrets-integrations-acceptance.md). 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.
