Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,20 @@ See [STATUS.md](server/STATUS.md) to learn more about which features will remain

## UNRELEASED

- Installations carry what the integration proxy needs (#1700, answers 1–3;
provisional):
- `integrationAppAgent`: the installation's app id, a keyless
`atomic:agent:<pubkey>`. `installRelease` mints it in the genesis the
user signs and discards the private key. The server refuses a value that
is not an agent id, and refuses to change it once set.
- Each node that activates a JS Installation publishes the agent it minted
for it on an `InstallationRuntime` child (`integrationRuntimeAgent`,
`name` = the node's device name). The node's agent signs its genesis and
may write it, so a page can register it with `POST /runtimes`.
- `integrationConnections`: `{platform: connection_id}`, written by the
page when it delegates. Server-side JS runs get it as `ctx.connections`,
and the app id as `ctx.app`, next to `ctx.config`; the host's values
replace any the caller sent.
- Server-side plugins reach the integration proxy through `ctx.http` signed
by the host (ontola/atomic-plugins#54, decisions 8 and 12). New option
`--integration-proxy-url` / `ATOMIC_INTEGRATION_PROXY_URL`: the proxy's
Expand Down
14 changes: 14 additions & 0 deletions TESTING_COVERAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,20 @@ checks `GET /app-agent` reports the identity activation mints for a JS
Installation. Not covered: a real integration proxy (atomic-plugins#122)
accepting these requests, delegations and `POST /runtimes`, and a second node.

Installation identities for the proxy (#1700, answers 1–3):
`plugins::installation_identity` tests commit real Installations and check that
a keyless `integrationAppAgent` is stored, refused when it is not an agent id,
and can be added but never changed; that activation publishes the node's agent
once on an `InstallationRuntime` child, written by that agent and writable by
it; that `integrationConnections` must map platforms to id strings; and that a
server-side JS run gets `ctx.app` and `ctx.connections` from the Installation,
over whatever the caller sent. `browser/lib/src/plugin-install.test.ts` checks
`installRelease` records a fresh `atomic:agent:` in the genesis with no key
material. Not covered: the page reading the runtime child and calling
`POST /runtimes`, the page writing `integrationConnections` when it delegates,
a second node publishing its own runtime child, and syncing those children
between nodes.

Issues view: `TablePage/Issues/issueStatus.test.ts` covers reading open/closed
status tags and booleans, picking close/reopen targets, and title/`#number`
filtering; `browser/e2e/tests/issues-view.spec.ts` covers the Issues view for
Expand Down
28 changes: 27 additions & 1 deletion browser/lib/src/ontologies/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ export const server = {
release: 'https://atomicdata.dev/classes/Release',
installation: 'https://atomicdata.dev/classes/Installation',
listing: 'https://atomicdata.dev/classes/Listing',
installationRuntime: 'https://atomicdata.dev/classes/InstallationRuntime',
},
properties: {
agent: 'https://atomicdata.dev/properties/invite/agent',
Expand Down Expand Up @@ -78,6 +79,12 @@ export const server = {
standards: 'https://atomicdata.dev/properties/standards',
evidence: 'https://atomicdata.dev/properties/evidence',
supportTier: 'https://atomicdata.dev/properties/supportTier',
integrationAppAgent:
'https://atomicdata.dev/properties/integrationAppAgent',
integrationConnections:
'https://atomicdata.dev/properties/integrationConnections',
integrationRuntimeAgent:
'https://atomicdata.dev/properties/integrationRuntimeAgent',
},
__classDefs: {
['https://atomicdata.dev/classes/Drive']: [
Expand Down Expand Up @@ -163,6 +170,8 @@ export const server = {
'https://atomicdata.dev/properties/pluginPermissions',
'https://atomicdata.dev/properties/jsonSchema',
'https://atomicdata.dev/properties/version',
'https://atomicdata.dev/properties/integrationAppAgent',
'https://atomicdata.dev/properties/integrationConnections',
],
['https://atomicdata.dev/classes/Listing']: [
'https://atomicdata.dev/properties/name',
Expand All @@ -175,6 +184,10 @@ export const server = {
'https://atomicdata.dev/properties/evidence',
'https://atomicdata.dev/properties/supportTier',
],
['https://atomicdata.dev/classes/InstallationRuntime']: [
'https://atomicdata.dev/properties/integrationRuntimeAgent',
'https://atomicdata.dev/properties/name',
],
},
} as const satisfies OntologyBaseObject;

Expand All @@ -191,6 +204,7 @@ export namespace Server {
export type Release = typeof server.classes.release;
export type Installation = typeof server.classes.installation;
export type Listing = typeof server.classes.listing;
export type InstallationRuntime = typeof server.classes.installationRuntime;
}

declare module '../index.js' {
Expand Down Expand Up @@ -297,7 +311,9 @@ declare module '../index.js' {
| typeof server.properties.pluginAgent
| typeof server.properties.pluginPermissions
| typeof server.properties.jsonSchema
| typeof server.properties.version;
| typeof server.properties.version
| typeof server.properties.integrationAppAgent
| typeof server.properties.integrationConnections;
};
[server.classes.listing]: {
requires:
Expand All @@ -313,6 +329,10 @@ declare module '../index.js' {
| typeof server.properties.evidence
| typeof server.properties.supportTier;
};
[server.classes.installationRuntime]: {
requires: BaseProps | typeof server.properties.integrationRuntimeAgent;
recommends: 'https://atomicdata.dev/properties/name';
};
}

interface PropTypeMapping {
Expand Down Expand Up @@ -370,6 +390,9 @@ declare module '../index.js' {
[server.properties.standards]: string[];
[server.properties.evidence]: JSONValue;
[server.properties.supportTier]: string;
[server.properties.integrationAppAgent]: string;
[server.properties.integrationConnections]: JSONValue;
[server.properties.integrationRuntimeAgent]: string;
}

interface PropSubjectToNameMapping {
Expand Down Expand Up @@ -427,5 +450,8 @@ declare module '../index.js' {
[server.properties.standards]: 'standards';
[server.properties.evidence]: 'evidence';
[server.properties.supportTier]: 'supportTier';
[server.properties.integrationAppAgent]: 'integrationAppAgent';
[server.properties.integrationConnections]: 'integrationConnections';
[server.properties.integrationRuntimeAgent]: 'integrationRuntimeAgent';
}
}
29 changes: 29 additions & 0 deletions browser/lib/src/plugin-install.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,35 @@ describe('installRelease', () => {
);
});

it('records a fresh keyless app id for the integration proxy', async () => {
const { store } = await testStore();
const install = () =>
installRelease(store, {
drive: 'https://example.com/drive',
release: { url: 'https://example.com/releases/1', id: 'blake3:1' },
name: 'importer',
grants: [],
});

const first = store.getResourceLoading(await install());
const second = store.getResourceLoading(await install());
const app = first.get(server.properties.integrationAppAgent);

// An agent id, and nothing that could sign as it.
expect(app).toMatch(/^atomic:agent:[A-Za-z0-9_-]{43}=?$/);
expect(second.get(server.properties.integrationAppAgent)).not.toBe(app);
expect(JSON.stringify(first.getLoroDoc()?.toJSON())).not.toMatch(
/privateKey|secret/i,
);
// Part of the genesis the user signs, not a later edit.
expect(
first
.getLoroDoc()
?.getMap('datatypes')
.get(server.properties.integrationAppAgent),
).toBe('atomicUrl');
});

it('leaves optional fields off and honours a draft status', async () => {
const { store } = await testStore();
const subject = await installRelease(store, {
Expand Down
19 changes: 19 additions & 0 deletions browser/lib/src/plugin-install.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,12 @@
* marketplace".
*/
import { signRequest } from './authentication.js';
import { generateKeyPair } from './CryptoProvider.js';
import { Datatype } from './datatypes.js';
import { core } from './ontologies/core.js';
import { server, type Server } from './ontologies/server.js';
import type { Store } from './store.js';
import { agentSubject } from './subject.js';
import type { JSONValue } from './value.js';

export const RUNTIME_JS = 'atomic-js/1';
Expand Down Expand Up @@ -218,6 +220,19 @@ export function installationIdentifier(name: string): string {
return cleaned || 'plugin';
}

/**
* A fresh app id for an Installation at the integration proxy
* (ontola/atomic-plugins#54, phase 2): the public `atomic:agent:<key>` of a
* keypair whose private key is dropped here, so nobody can ever sign as it.
* Proxy delegations and frame capabilities name it; every node that runs the
* Installation signs as its own agent, registered as a runtime of this one.
*/
export async function mintInstallationAppId(): Promise<string> {
const { publicKey } = await generateKeyPair();

return agentSubject(publicKey);
}

export interface InstallReleaseOptions {
drive: string;
release: ReleaseReference;
Expand Down Expand Up @@ -265,6 +280,9 @@ export async function installRelease(
[server.properties.releaseId]: release.id,
[server.properties.installationStatus]: status,
[server.properties.grants]: grants,
// In the genesis, so the user's own signature is what records it. The
// server refuses to change it afterwards.
[server.properties.integrationAppAgent]: await mintInstallationAppId(),
};
if (namespace) propVals[server.properties.namespace] = namespace;
if (description) propVals[core.properties.description] = description;
Expand All @@ -288,6 +306,7 @@ export async function installRelease(
[server.properties.namespace]: Datatype.STRING,
[server.properties.version]: Datatype.STRING,
[server.properties.config]: Datatype.JSON,
[server.properties.integrationAppAgent]: Datatype.ATOMIC_URL,
},
});
await installation.save();
Expand Down
52 changes: 51 additions & 1 deletion lib/defaults/plugins.json
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,38 @@
"https://atomicdata.dev/properties/parent": "https://atomicdata.dev/properties",
"https://atomicdata.dev/properties/shortname": "installation-status"
},
{
"@id": "https://atomicdata.dev/properties/integrationAppAgent",
"https://atomicdata.dev/properties/classtype": "https://atomicdata.dev/classes/Agent",
"https://atomicdata.dev/properties/datatype": "https://atomicdata.dev/datatypes/atomicURL",
"https://atomicdata.dev/properties/description": "The Installation's app id at the integration proxy: a keyless `atomic:agent:<public key>` that the installing page generated and recorded in a commit signed by the user, discarding the private key. Proxy delegations and frame capabilities name it; nobody signs as it. Each node's own agent for the Installation is registered as a runtime of it. It cannot change once set.",
"https://atomicdata.dev/properties/isA": [
"https://atomicdata.dev/classes/Property"
],
"https://atomicdata.dev/properties/parent": "https://atomicdata.dev/properties",
"https://atomicdata.dev/properties/shortname": "integration-app-agent"
},
{
"@id": "https://atomicdata.dev/properties/integrationConnections",
"https://atomicdata.dev/properties/datatype": "https://atomicdata.dev/datatypes/json",
"https://atomicdata.dev/properties/description": "The integration-proxy connections delegated to an Installation, as a JSON object `{platform: connection_id}`. The page writes it when it delegates; it is not secret. The host passes it to the plugin as `ctx.connections`.",
"https://atomicdata.dev/properties/isA": [
"https://atomicdata.dev/classes/Property"
],
"https://atomicdata.dev/properties/parent": "https://atomicdata.dev/properties",
"https://atomicdata.dev/properties/shortname": "integration-connections"
},
{
"@id": "https://atomicdata.dev/properties/integrationRuntimeAgent",
"https://atomicdata.dev/properties/classtype": "https://atomicdata.dev/classes/Agent",
"https://atomicdata.dev/properties/datatype": "https://atomicdata.dev/datatypes/atomicURL",
"https://atomicdata.dev/properties/description": "On an InstallationRuntime: the agent one node minted for the Installation when it activated it. The node signs its integration-proxy requests with it, and the page registers it as a runtime of the Installation's app.",
"https://atomicdata.dev/properties/isA": [
"https://atomicdata.dev/classes/Property"
],
"https://atomicdata.dev/properties/parent": "https://atomicdata.dev/properties",
"https://atomicdata.dev/properties/shortname": "integration-runtime-agent"
},
{
"@id": "https://atomicdata.dev/properties/domains",
"https://atomicdata.dev/properties/datatype": "https://atomicdata.dev/datatypes/json",
Expand Down Expand Up @@ -326,7 +358,9 @@
"https://atomicdata.dev/properties/pluginAgent",
"https://atomicdata.dev/properties/pluginPermissions",
"https://atomicdata.dev/properties/jsonSchema",
"https://atomicdata.dev/properties/version"
"https://atomicdata.dev/properties/version",
"https://atomicdata.dev/properties/integrationAppAgent",
"https://atomicdata.dev/properties/integrationConnections"
],
"https://atomicdata.dev/properties/requires": [
"https://atomicdata.dev/properties/release",
Expand All @@ -336,6 +370,22 @@
"https://atomicdata.dev/properties/shortname": "installation",
"https://atomicdata.dev/properties/subresources": []
},
{
"@id": "https://atomicdata.dev/classes/InstallationRuntime",
"https://atomicdata.dev/properties/description": "A child of an Installation on which one node publishes the agent it minted for that Installation. The node creates it when it activates the Installation, signed by that agent, which may write it.",
"https://atomicdata.dev/properties/isA": [
"https://atomicdata.dev/classes/Class"
],
"https://atomicdata.dev/properties/parent": "https://atomicdata.dev/classes",
"https://atomicdata.dev/properties/recommends": [
"https://atomicdata.dev/properties/name"
],
"https://atomicdata.dev/properties/requires": [
"https://atomicdata.dev/properties/integrationRuntimeAgent"
],
"https://atomicdata.dev/properties/shortname": "installation-runtime",
"https://atomicdata.dev/properties/subresources": []
},
{
"@id": "https://atomicdata.dev/classes/Listing",
"https://atomicdata.dev/properties/description": "A marketplace entry pointing at a Release. Any Drive of Listings is a marketplace.",
Expand Down
13 changes: 13 additions & 0 deletions lib/src/urls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ pub const TABLE: &str = "https://atomicdata.dev/classes/Table";
pub const PLUGIN: &str = "https://atomicdata.dev/classes/Plugin";
pub const RELEASE: &str = "https://atomicdata.dev/classes/Release";
pub const INSTALLATION: &str = "https://atomicdata.dev/classes/Installation";
pub const INSTALLATION_RUNTIME: &str = "https://atomicdata.dev/classes/InstallationRuntime";
pub const LISTING: &str = "https://atomicdata.dev/classes/Listing";
pub const TAG: &str = "https://atomicdata.dev/classes/Tag";
pub const PEER: &str = "https://atomicdata.dev/classes/Peer";
Expand Down Expand Up @@ -248,6 +249,18 @@ pub const PUBLISHER: &str = "https://atomicdata.dev/properties/publisher";
pub const RELEASE_PROP: &str = "https://atomicdata.dev/properties/release";
pub const GRANTS: &str = "https://atomicdata.dev/properties/grants";
pub const INSTALLATION_STATUS: &str = "https://atomicdata.dev/properties/installationStatus";
// ... for the integration proxy (ontola/atomic-plugins#54, phase 2)
/// The installation's keyless app id at the integration proxy: an
/// `atomic:agent:<pubkey>` the installing page minted and whose private key it
/// discarded. Delegations and runtimes name it; nobody signs as it.
pub const INTEGRATION_APP_AGENT: &str = "https://atomicdata.dev/properties/integrationAppAgent";
/// `{platform: connection_id}`: the proxy connections delegated to an
/// installation, written by the page when it delegates. Not secret.
pub const INTEGRATION_CONNECTIONS: &str =
"https://atomicdata.dev/properties/integrationConnections";
/// On an `InstallationRuntime`: the node's own app agent for the installation.
pub const INTEGRATION_RUNTIME_AGENT: &str =
"https://atomicdata.dev/properties/integrationRuntimeAgent";
pub const DOMAINS: &str = "https://atomicdata.dev/properties/domains";
pub const STANDARDS: &str = "https://atomicdata.dev/properties/standards";
pub const EVIDENCE: &str = "https://atomicdata.dev/properties/evidence";
Expand Down
6 changes: 6 additions & 0 deletions server/src/plugins/host_core.rs
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,12 @@ pub trait PluginHost: Send + 'static {
async fn resource_grants(&mut self) -> ResourceGrants {
ResourceGrants::default()
}
/// Keys the host sets on the run's input, over whatever the caller sent:
/// for an Installation, `app` and `connections` (#1700, answers 1 and 3).
/// A host without an Installation adds nothing.
async fn run_context(&mut self) -> serde_json::Map<String, serde_json::Value> {
serde_json::Map::new()
}
}

/// The resource grants of a JS plugin: the approved `grants` of the
Expand Down
Loading
Loading