Skip to content

Installation app ids, published node agents and delegated connections for the integration proxy (#1700, answers 1-3) - #1710

Closed
michielbdejong wants to merge 2 commits into
claude/installation-proxy-signingfrom
claude/installation-app-identity
Closed

michielbdejong wants to merge 2 commits into
claude/installation-proxy-signingfrom
claude/installation-app-identity

Conversation

@michielbdejong

Copy link
Copy Markdown
Contributor

Answers 1–3 of #1700, the atomic-server side of phase 2 of ontola/atomic-plugins#54. Stacked on #1702. The answers are provisional, so all the reading and writing lives in one module, server/src/plugins/installation_identity.rs.

1. An app id per Installation

  • New property integrationAppAgent (integration-app-agent, atomicURL, classtype Agent). It holds a keyless atomic:agent:<pubkey>.
  • Data browser: installRelease (in @tomic/lib) mints the id with mintInstallationAppId(), which generates a keypair and keeps only the public key. It writes the id in the genesis, so the user's signature records it. Both the catalog install (IntegrationStore) and NewPluginButton go through installRelease, so no UI changes were needed.
  • Server: the Installation's before-commit hook refuses a value that isn't an agent id with a valid Ed25519 key. It also refuses to change the id once it's set, because proxy delegations and runtimes name it. You can still add an id to an older Installation that has none.
  • Exposed to server-side JS runs as ctx.app. Frames get it from the page, which can read it directly off the Installation.

2. Publishing the node's agent

  • New class InstallationRuntime (installation-runtime), with integrationRuntimeAgent (required) and name.
  • After a commit to an active Installation, a new after-commit hook calls publish_runtime. If this node has an active app agent for the Installation, it creates one child of the Installation with:
    • integrationRuntimeAgent set to that agent;
    • name set to the node's device name, which is the label for POST /runtimes;
    • write set to [that agent].
  • The genesis is signed by the node's agent itself, so a reader can check that the published agent wrote it. Minting stays at activation (ensure_js_identity).
  • It's idempotent: it looks the child up by agent and parent first. Because it runs on every commit to an active Installation, Installations activated before this change get their child on their next commit.
  • It's best effort. A failure is logged and never undoes the Installation commit.
  • The page-side POST /runtimes {app, agent, label} call isn't in this PR.

3. The delegated connection id

  • New property integrationConnections (integration-connections, JSON): {platform: connection_id}. The before-commit hook refuses anything else: a non-object, a non-string or empty id, or an empty platform.
  • A new PluginHost::run_context() hook (the default adds nothing) lets StoreHost read the Installation the run resolves to. JsRuntime::run_inner then sets connections ({} when there are none) and app (null when unset) on the run input, next to config.
  • The host's values replace whatever the caller sent. This covers every server-side entry point: /plugin-run, schedules, triggers, sync sessions and actions. It leaves describe runs and non-Installation hosts byte-for-byte unchanged.
  • The page writing integrationConnections when it delegates isn't in this PR.

The ontology changes are in lib/defaults/plugins.json, lib/src/urls.rs and browser/lib/src/ontologies/server.ts. The Installation class now recommends the two new properties.

Tests (written first)

  • plugins::installation_identity (8 tests):
    • the app id is stored, and it isn't the node's agent;
    • a malformed id is refused (a URL, an empty key, a short key, a commit id); the legacy did:ad:agent: spelling is accepted;
    • an id can be added later, and a change is refused;
    • activation publishes one runtime child, whose write is the node agent and whose genesis signer is the node agent; a second commit publishes nothing new;
    • a node without an agent publishes nothing;
    • malformed connections are refused;
    • a real embedded-runtime run gets ctx.connections and ctx.app from the Installation, next to ctx.config; forged caller values are overridden, and a later delegation reaches the next run;
    • an Installation without either property gets {} and null.
  • browser/lib/src/plugin-install.test.ts: installRelease records a fresh atomic:agent: for each install, with the atomicUrl tag, in the genesis, and with no key material.
  • cargo test -p atomic-server --lib: 285 passed, 1 failed. The failure was triggers::a_hard_restart_delivers_a_saved_arrival_once, a crash/restart test; it passes when run alone and doesn't touch Installations.
  • cargo test -p atomic_lib --features db-redb --lib: 657 passed.
  • browser/lib vitest: 965 passed.
  • cargo clippy -p atomic-server -p atomic_lib --tests is clean.

No UI changes.

Open questions

  • Revocation: the runtime child stays after a revoke, so the page can still read the agent to DELETE /runtimes/{agent}. Should the node delete it or mark it once that's done?
  • Sync: the child's genesis is applied locally without a rights check, because it is the node's own agent writing under an Installation it can't otherwise write. Another node that receives it through /commit, and not through snapshot sync, might refuse it. Sync of these children isn't tested.
  • Other entry points: I left GET /app-agent unchanged. The page can read the app id from the Installation and the runtimes from its children. It could return both in one call if that turns out to be useful.
  • Browser-placed runs don't get ctx.connections. They have no network access, so they can't reach the proxy anyway.

Refs #1700, ontola/atomic-plugins#54, ontola/atomic-plugins#122.

🤖 Generated with Claude Code

… connections (#1700)

Answers 1-3 of #1700 (ontola/atomic-plugins#54, phase 2), provisional:

- integrationAppAgent: a keyless atomic:agent:<pubkey> that installRelease
  mints in the genesis the user signs, discarding the private key. The
  server refuses a value that is not an agent id, and refuses to change it
  once set.
- On activation, each node publishes the agent it minted for a JS
  Installation on an InstallationRuntime child, signed by and writable by
  that agent, so the page can register it with POST /runtimes.
- integrationConnections ({platform: connection_id}) reaches server-side
  JS runs as ctx.connections, with the app id as ctx.app, next to
  ctx.config. The host's values replace any the caller sent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The after-commit hook runs outside the Installation's subject lock, so two
commits landing together both missed the runtime lookup and both created a
child. A duplicate is permanent and syncs to every client. A process-wide
lock now covers the lookup and the create; a publish is rare, and once the
child exists it is only the lookup.

The test fires eight publishes on separate threads, released together. It
left seven children before the lock and leaves one now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@michielbdejong

Copy link
Copy Markdown
Contributor Author

Merge-risk triage (2026-09-28). This is a read-only review of this PR's own diff. The rule it applies: nothing that works today may break for existing users or clients, and new behaviour is added alongside the old. The stack is being rebased onto develop as one chain before merging, so line references are against the current stacked base.

Verdict: SAFE-WITH-FIX

Otherwise additive: new properties and class, and integrationAppAgent is minted into new installs and guarded so it can't change once set.

Fix before merging: on_installation_after_commit → publish_runtime runs on every commit to every active JS Installation, including existing ones and plugins that never use the proxy (wasm-plugins is a default feature), and creates an InstallationRuntime in the user's drive. Only publish when the release manifest declares proxy (or integrationConnections is set), the same gate #1733 uses on the frontend. This one gate also removes most of the risk in #1836 and #1833. Minor: run_context overwrites any app/connections input keys a caller sent.

🤖 Generated with Claude Code

@michielbdejong

Copy link
Copy Markdown
Contributor Author

Closing as part of the plugin-host stack cleanup (Q-101): not needed by atomic-plugins now. See the inventory at #1726 (comment). The branch is kept, and pin candidates are unaffected. Closed by Claude (VPS coordinator) on behalf of Michiel.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request plugin Should probably be an Atomic Plugin server atomic-server

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant