diff --git a/browser/data-browser/src/chunks/PluginRuns/CatalogApps.tsx b/browser/data-browser/src/chunks/PluginRuns/CatalogApps.tsx new file mode 100644 index 0000000000..a9641e3477 --- /dev/null +++ b/browser/data-browser/src/chunks/PluginRuns/CatalogApps.tsx @@ -0,0 +1,221 @@ +import { useCallback, useEffect, useState } from 'react'; +import { styled } from 'styled-components'; +import toast from 'react-hot-toast'; +import { + catalogAppState, + installCatalogApp, + readConnectionSubjects, + readInstalledCatalogApps, + updateCatalogApp, + useStore, + type CatalogApp, + type InstalledCatalogApp, +} from '@tomic/react'; +import { Card } from '@components/Card'; +import { Column, Row } from '@components/Row'; +import { Button } from '@components/Button'; +import { constructOpenURL } from '@helpers/navigation'; +import { useNavigateWithTransition } from '@hooks/useNavigateWithTransition'; +import { handOverAppKey } from '@chunks/AppPage/appAgent'; +import type { CatalogEntry } from './pluginCatalog'; + +/** The catalog's app entries this visitor is offered, under the same gates as the rest of the page. */ +export function visibleCatalogApps( + entries: CatalogEntry[], + options: { query: string; showExperimental: boolean; showApi: boolean }, +): CatalogApp[] { + return entries + .filter( + entry => + entry.app && + entry.enabled && + (!entry.experimental || options.showExperimental) && + (!entry.requiresApiPlugins || options.showApi), + ) + .map(entry => entry.app!) + .filter(app => + [app.name, app.description ?? '', app.id] + .join(' ') + .toLocaleLowerCase() + .includes(options.query), + ); +} + +/** + * Drive apps offered by the plugin catalog (`app-module` entries): install + * one, open it, and move it to the catalog's version when that is newer. + * + * Installing downloads the module the entry names, refuses it unless its bytes + * match the entry's integrity hash, and makes an ordinary app from it — the + * same app, table, schema and identity the New menu makes. So nothing here is + * specific to any one app, and an installed app is edited, shared and deleted + * like any other. + */ +export function CatalogApps({ + entries, + drive, + query, + showExperimental, + showApi, +}: { + entries: CatalogEntry[]; + drive: string; + query: string; + showExperimental: boolean; + showApi: boolean; +}): React.JSX.Element | null { + const store = useStore(); + const navigate = useNavigateWithTransition(); + const [installed, setInstalled] = useState([]); + const [busy, setBusy] = useState(); + + const refresh = useCallback( + () => + readInstalledCatalogApps(store, drive, property => + readConnectionSubjects(store, drive, property), + ).then(setInstalled), + [store, drive], + ); + + useEffect(() => { + refresh().catch(() => setInstalled([])); + }, [refresh]); + + const apps = visibleCatalogApps(entries, { + query, + showExperimental, + showApi, + }); + + if (apps.length === 0) return null; + + const install = async (app: CatalogApp) => { + setBusy(app.id); + + try { + const created = await installCatalogApp(store, { drive, app }); + + // As for an app from the New menu: it still works if this fails, but + // cannot write as itself while nobody is signed in. + try { + await handOverAppKey(store, { + drive, + app: created.app, + secret: created.secret, + }); + } catch (error) { + store.notifyError(error); + } + + navigate(constructOpenURL(created.app)); + } catch (error) { + toast.error(String(error instanceof Error ? error.message : error)); + } finally { + setBusy(undefined); + } + }; + + const update = async (app: CatalogApp, subject: string) => { + setBusy(app.id); + + try { + await updateCatalogApp(store, { drive, subject, app }); + await refresh(); + toast.success(`${app.name} updated to ${app.version}`); + } catch (error) { + toast.error(String(error instanceof Error ? error.message : error)); + } finally { + setBusy(undefined); + } + }; + + return ( +
+ +

Drive apps

+

+ Apps that run in their own frame on this drive and keep their rows in + a table of their own. Each is a published version; installing checks + its code against the catalog before anything is saved. +

+ + {apps.map(app => { + const mine = installed.find(i => i.id === app.id); + const state = catalogAppState(app, mine); + + return ( + + + + {app.emoji ?? 'đź§©'} + + {mine + ? `Installed ${mine.version ?? '(unknown version)'}` + : `Version ${app.version}`} + + +
+

{app.name}

+ {app.description && {app.description}} +
+ + {state === 'install' ? ( + + ) : ( + + )} + {state === 'update' && ( + + )} + +
+
+ ); + })} +
+
+
+ ); +} + +const Grid = styled.div` + display: grid; + grid-template-columns: repeat(auto-fill, minmax(min(100%, 19rem), 1fr)); + gap: 1rem; + align-items: start; +`; +const Avatar = styled.div` + display: grid; + place-items: center; + width: 2.8rem; + height: 2.8rem; + border-radius: ${p => p.theme.radius}; + background: ${p => p.theme.colors.bg2}; + font-size: 1.3rem; +`; +const Muted = styled.p` + margin: 0; + color: ${p => p.theme.colors.textLight}; + font-size: 0.9rem; +`; diff --git a/browser/data-browser/src/chunks/PluginRuns/pluginCatalog.test.tsx b/browser/data-browser/src/chunks/PluginRuns/pluginCatalog.test.tsx index ba085fe3a1..086963b408 100644 --- a/browser/data-browser/src/chunks/PluginRuns/pluginCatalog.test.tsx +++ b/browser/data-browser/src/chunks/PluginRuns/pluginCatalog.test.tsx @@ -104,6 +104,27 @@ describe('parseCatalogEntries', () => { ).toEqual(['kept']); }); + it('reads an installable app, resolving its module against the catalog', () => { + const [entry] = parseCatalogEntries( + [ + row({ + 'https://atomicdata.dev/properties/name': 'Fixture', + [`${P}version`]: '1.2.3', + [`${P}app-module`]: 'fixture/app/ui.js', + [`${P}app-module-integrity`]: 'sha384-AAAA', + }), + row({ [SHORTNAME]: 'no-app' }), + ], + 'https://plugins.test/integrations/catalog.json', + ); + expect(entry.app).toMatchObject({ + id: 'fixture-api', + version: '1.2.3', + module: 'https://plugins.test/integrations/fixture/app/ui.js', + integrity: 'sha384-AAAA', + }); + }); + it('returns nothing for a non-array catalog', () => { expect(parseCatalogEntries({})).toEqual([]); expect(parseCatalogEntries(null)).toEqual([]); diff --git a/browser/data-browser/src/chunks/PluginRuns/pluginCatalog.ts b/browser/data-browser/src/chunks/PluginRuns/pluginCatalog.ts index 1bcf574478..7d1a7dd3e4 100644 --- a/browser/data-browser/src/chunks/PluginRuns/pluginCatalog.ts +++ b/browser/data-browser/src/chunks/PluginRuns/pluginCatalog.ts @@ -1,4 +1,5 @@ import { useEffect, useState } from 'react'; +import { parseCatalogApp, type CatalogApp } from '@tomic/react'; import { usePluginCatalogUrl } from '@helpers/pluginCatalogUrl'; const CATALOG_ENTRY_CLASS = @@ -18,6 +19,8 @@ export interface CatalogEntry { experimental: boolean; enabled: boolean; requiresApiPlugins: boolean; + /** Set when the entry is an installable drive app (`app-module`). */ + app?: CatalogApp; } function isRecord(value: unknown): value is Record { @@ -25,7 +28,10 @@ function isRecord(value: unknown): value is Record { } /** Malformed entries are skipped, so one bad row can't hide the rest. */ -export function parseCatalogEntries(raw: unknown): CatalogEntry[] { +export function parseCatalogEntries( + raw: unknown, + catalogUrl?: string, +): CatalogEntry[] { if (!Array.isArray(raw)) return []; return raw.flatMap((resource): CatalogEntry[] => { @@ -42,6 +48,9 @@ export function parseCatalogEntries(raw: unknown): CatalogEntry[] { experimental: resource[EXPERIMENTAL_PROP] !== false, enabled: resource[ENABLED_PROP] === true, requiresApiPlugins: resource[REQUIRES_API_PLUGINS_PROP] === true, + // Resolved against the catalog it came from, so a catalog can name + // its modules relative to itself. + ...(catalogUrl ? { app: parseCatalogApp(resource, catalogUrl) } : {}), }, ]; }); @@ -77,7 +86,7 @@ function fetchIntegrationCatalog(catalogUrl: string): Promise { return response.json(); }) - .then(parseCatalogEntries) + .then(raw => parseCatalogEntries(raw, catalogUrl)) .then(entries => { resolved.set(catalogUrl, entries); @@ -97,6 +106,8 @@ export function useIntegrationCatalog(): { entries: CatalogEntry[]; ready: boolean; error?: string; + /** Where the entries came from. */ + catalogUrl: string; } { const catalogUrl = usePluginCatalogUrl(); const [entries, setEntries] = useState(() => resolved.get(catalogUrl)); @@ -118,7 +129,12 @@ export function useIntegrationCatalog(): { }; }, [catalogUrl]); - return { entries: entries ?? [], ready: entries !== undefined, error }; + return { + entries: entries ?? [], + ready: entries !== undefined, + error, + catalogUrl, + }; } /** diff --git a/browser/data-browser/src/locales/de.po b/browser/data-browser/src/locales/de.po index 6175af1b39..36c395226f 100644 --- a/browser/data-browser/src/locales/de.po +++ b/browser/data-browser/src/locales/de.po @@ -1895,6 +1895,7 @@ msgstr "" #: src/actions/resourceActions.tsx #: src/chunks/DashboardPage/blocks/ViewBlock.tsx +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/chunks/TablePage/Issues/IssueRow.tsx #: src/chunks/TablePage/Kanban/KanbanCard.tsx #: src/routes/IntegrationStore.tsx @@ -3013,6 +3014,7 @@ msgstr "" msgid "Enter valid JSON..." msgstr "" +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/views/Installation/InstallationPage.tsx msgid "Install" msgstr "" @@ -8485,7 +8487,9 @@ msgstr "" msgid "Previous version" msgstr "" +#. 0: app.version #. 0: status.state!.deployments.indexOf(entry.deployment) + 1 +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/chunks/Website/WebsiteHosting.tsx msgid "Version {0}" msgstr "" @@ -9424,3 +9428,45 @@ msgstr "" #: src/chunks/AppPage/AppFrame.tsx msgid "Connect an account" msgstr "" + +#. 0: app.name; 1: app.version +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "{0} updated to {1}" +msgstr "" + +#. 0: mine.version ?? '(unknown version)' +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Installed {0}" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Installing…" +msgstr "" + +#. 0: app.name +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Install {0}" +msgstr "" + +#. 0: app.name +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Open {0}" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Updating…" +msgstr "" + +#. 0: app.version +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Update to {0}" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Drive apps" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Apps that run in their own frame on this drive and keep their rows in a table of their own. Each is a published version; installing checks its code against the catalog before anything is saved." +msgstr "" diff --git a/browser/data-browser/src/locales/en.po b/browser/data-browser/src/locales/en.po index 22960acfe1..a9b498521a 100644 --- a/browser/data-browser/src/locales/en.po +++ b/browser/data-browser/src/locales/en.po @@ -1895,6 +1895,7 @@ msgstr "Toggle whether this resource appears in your Favorites." #: src/actions/resourceActions.tsx #: src/chunks/DashboardPage/blocks/ViewBlock.tsx +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/chunks/TablePage/Issues/IssueRow.tsx #: src/chunks/TablePage/Kanban/KanbanCard.tsx #: src/routes/IntegrationStore.tsx @@ -3013,6 +3014,7 @@ msgstr "Copy code" msgid "Enter valid JSON..." msgstr "Enter valid JSON..." +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/views/Installation/InstallationPage.tsx msgid "Install" msgstr "Install" @@ -8496,7 +8498,9 @@ msgstr "Publish site" msgid "Previous version" msgstr "Previous version" +#. 0: app.version #. 0: status.state!.deployments.indexOf(entry.deployment) + 1 +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/chunks/Website/WebsiteHosting.tsx msgid "Version {0}" msgstr "Version {0}" @@ -9442,3 +9446,45 @@ msgstr "This app wants to connect your{0} <0/> account through{1} {2}. The conne #: src/chunks/AppPage/AppFrame.tsx msgid "Connect an account" msgstr "Connect an account" + +#. 0: app.name; 1: app.version +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "{0} updated to {1}" +msgstr "{0} updated to {1}" + +#. 0: mine.version ?? '(unknown version)' +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Installed {0}" +msgstr "Installed {0}" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Installing…" +msgstr "Installing…" + +#. 0: app.name +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Install {0}" +msgstr "Install {0}" + +#. 0: app.name +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Open {0}" +msgstr "Open {0}" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Updating…" +msgstr "Updating…" + +#. 0: app.version +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Update to {0}" +msgstr "Update to {0}" + +#: src/chunks/PluginRuns/CatalogApps.tsx +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Drive apps" +msgstr "Drive apps" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Apps that run in their own frame on this drive and keep their rows in a table of their own. Each is a published version; installing checks its code against the catalog before anything is saved." +msgstr "Apps that run in their own frame on this drive and keep their rows in a table of their own. Each is a published version; installing checks its code against the catalog before anything is saved." diff --git a/browser/data-browser/src/locales/es.po b/browser/data-browser/src/locales/es.po index 58f207142a..16a681ea50 100644 --- a/browser/data-browser/src/locales/es.po +++ b/browser/data-browser/src/locales/es.po @@ -1895,6 +1895,7 @@ msgstr "" #: src/actions/resourceActions.tsx #: src/chunks/DashboardPage/blocks/ViewBlock.tsx +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/chunks/TablePage/Issues/IssueRow.tsx #: src/chunks/TablePage/Kanban/KanbanCard.tsx #: src/routes/IntegrationStore.tsx @@ -3013,6 +3014,7 @@ msgstr "Copiar código" msgid "Enter valid JSON..." msgstr "Introduce un JSON válido..." +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/views/Installation/InstallationPage.tsx msgid "Install" msgstr "Instalar" @@ -8485,7 +8487,9 @@ msgstr "" msgid "Previous version" msgstr "" +#. 0: app.version #. 0: status.state!.deployments.indexOf(entry.deployment) + 1 +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/chunks/Website/WebsiteHosting.tsx msgid "Version {0}" msgstr "" @@ -9424,3 +9428,45 @@ msgstr "" #: src/chunks/AppPage/AppFrame.tsx msgid "Connect an account" msgstr "" + +#. 0: app.name; 1: app.version +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "{0} updated to {1}" +msgstr "" + +#. 0: mine.version ?? '(unknown version)' +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Installed {0}" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Installing…" +msgstr "" + +#. 0: app.name +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Install {0}" +msgstr "" + +#. 0: app.name +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Open {0}" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Updating…" +msgstr "" + +#. 0: app.version +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Update to {0}" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Drive apps" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Apps that run in their own frame on this drive and keep their rows in a table of their own. Each is a published version; installing checks its code against the catalog before anything is saved." +msgstr "" diff --git a/browser/data-browser/src/locales/fr.po b/browser/data-browser/src/locales/fr.po index b43fb625f4..46af9aef47 100644 --- a/browser/data-browser/src/locales/fr.po +++ b/browser/data-browser/src/locales/fr.po @@ -1895,6 +1895,7 @@ msgstr "" #: src/actions/resourceActions.tsx #: src/chunks/DashboardPage/blocks/ViewBlock.tsx +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/chunks/TablePage/Issues/IssueRow.tsx #: src/chunks/TablePage/Kanban/KanbanCard.tsx #: src/routes/IntegrationStore.tsx @@ -3013,6 +3014,7 @@ msgstr "Copier le code" msgid "Enter valid JSON..." msgstr "Entrez un JSON valide..." +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/views/Installation/InstallationPage.tsx msgid "Install" msgstr "Installer" @@ -8485,7 +8487,9 @@ msgstr "" msgid "Previous version" msgstr "" +#. 0: app.version #. 0: status.state!.deployments.indexOf(entry.deployment) + 1 +#: src/chunks/PluginRuns/CatalogApps.tsx #: src/chunks/Website/WebsiteHosting.tsx msgid "Version {0}" msgstr "" @@ -9424,3 +9428,45 @@ msgstr "" #: src/chunks/AppPage/AppFrame.tsx msgid "Connect an account" msgstr "" + +#. 0: app.name; 1: app.version +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "{0} updated to {1}" +msgstr "" + +#. 0: mine.version ?? '(unknown version)' +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Installed {0}" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Installing…" +msgstr "" + +#. 0: app.name +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Install {0}" +msgstr "" + +#. 0: app.name +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Open {0}" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Updating…" +msgstr "" + +#. 0: app.version +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Update to {0}" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Drive apps" +msgstr "" + +#: src/chunks/PluginRuns/CatalogApps.tsx +msgid "Apps that run in their own frame on this drive and keep their rows in a table of their own. Each is a published version; installing checks its code against the catalog before anything is saved." +msgstr "" diff --git a/browser/data-browser/src/routes/IntegrationStore.tsx b/browser/data-browser/src/routes/IntegrationStore.tsx index ea8993a7db..93d7c5d9ee 100644 --- a/browser/data-browser/src/routes/IntegrationStore.tsx +++ b/browser/data-browser/src/routes/IntegrationStore.tsx @@ -1,6 +1,10 @@ import { usePluginClass } from '../chunks/PluginRuns/runScript'; import { NewAutomation } from '../chunks/PluginRuns/NewAutomation'; import { ConnectedIntegration } from '../chunks/PluginRuns/ConnectedIntegration'; +import { + CatalogApps, + visibleCatalogApps, +} from '../chunks/PluginRuns/CatalogApps'; import { hasExperimentalEntries, useIntegrationCatalog, @@ -76,7 +80,8 @@ function IntegrationStore(): React.JSX.Element { const { drive } = useSettings(); // Opened from a workspace: new automations can belong to it. const { workspace } = IntegrationStoreRoute.useSearch(); - const { showExperimentalPlugins, setVisibility } = useIntegrationVisibility(); + const { showExperimentalPlugins, showApiPlugins, setVisibility } = + useIntegrationVisibility(); const { entries: catalogEntries, ready: catalogReady, @@ -283,7 +288,12 @@ function IntegrationStore(): React.JSX.Element { .toLocaleLowerCase() .includes(query), ); - const nothingToDiscover = catalogReady && !visible?.length; + const appsShown = visibleCatalogApps(catalogEntries, { + query, + showExperimental: showExperimentalPlugins, + showApi: showApiPlugins, + }).length; + const nothingToDiscover = catalogReady && !visible?.length && !appsShown; return (
@@ -370,6 +380,15 @@ function IntegrationStore(): React.JSX.Element { )} {nothingToDiscover && } + {drive && ( + + )} {visible && visible.length > 0 && ( <> diff --git a/browser/lib/src/catalog-app.test.ts b/browser/lib/src/catalog-app.test.ts new file mode 100644 index 0000000000..4c4fad7500 --- /dev/null +++ b/browser/lib/src/catalog-app.test.ts @@ -0,0 +1,130 @@ +import { describe, expect, it } from 'vitest'; +import { + catalogAppProperties as p, + catalogAppState, + compareVersions, + fetchCatalogAppModule, + parseCatalogApp, + subresourceIntegrity, +} from './catalog-app.js'; + +const CATALOG = + 'https://ontola.github.io/atomic-plugins/integrations/catalog.json'; +const SOURCE = + 'export async function view({ root }) { root.textContent = "hi"; }'; + +const entry = (overrides: Record = {}) => ({ + [p.shortname]: 'pets', + [p.name]: 'Pets', + [p.version]: '0.1.0', + [p.module]: 'https://cdn.jsdelivr.net/npm/atomic-app-pets@0.1.0/ui.js', + [p.integrity]: 'sha384-AAAA', + ...overrides, +}); + +const serve = + (body: string, status = 200): typeof fetch => + async () => + new Response(body, { status }); + +describe('parseCatalogApp', () => { + it('reads an app entry', () => { + expect( + parseCatalogApp( + entry({ [p.rowName]: 'Pet', [p.rowNamePlural]: 'Pets' }), + CATALOG, + ), + ).toMatchObject({ + id: 'pets', + version: '0.1.0', + module: 'https://cdn.jsdelivr.net/npm/atomic-app-pets@0.1.0/ui.js', + rowName: { singular: 'Pet', plural: 'Pets' }, + }); + }); + + it('skips entries that are not installable apps', () => { + expect(parseCatalogApp(entry({ [p.module]: undefined }), CATALOG)).toBe( + undefined, + ); + expect(parseCatalogApp(entry({ [p.version]: undefined }), CATALOG)).toBe( + undefined, + ); + expect(parseCatalogApp(entry({ [p.integrity]: 'md5-x' }), CATALOG)).toBe( + undefined, + ); + expect( + parseCatalogApp( + entry({ [p.module]: 'http://example.com/ui.js' }), + CATALOG, + ), + ).toBe(undefined); + expect(parseCatalogApp('nope', CATALOG)).toBe(undefined); + }); + + it('resolves a relative module against the catalog, and allows loopback HTTP', () => { + expect( + parseCatalogApp(entry({ [p.module]: 'pets/app/ui.js' }), CATALOG)?.module, + ).toBe( + 'https://ontola.github.io/atomic-plugins/integrations/pets/app/ui.js', + ); + expect( + parseCatalogApp( + entry({ + [p.module]: 'http://localhost:9881/integrations/pets/app/ui.js', + }), + CATALOG, + )?.module, + ).toBe('http://localhost:9881/integrations/pets/app/ui.js'); + }); +}); + +describe('fetchCatalogAppModule', () => { + it('returns bytes that match the pinned integrity', async () => { + const integrity = await subresourceIntegrity(SOURCE); + expect(integrity).toMatch(/^sha384-/); + const app = { + ...parseCatalogApp(entry({ [p.integrity]: integrity }), CATALOG)!, + }; + await expect(fetchCatalogAppModule(app, serve(SOURCE))).resolves.toBe( + SOURCE, + ); + }); + + it('refuses bytes that do not match, and failed downloads', async () => { + const app = { + ...parseCatalogApp( + entry({ [p.integrity]: await subresourceIntegrity(SOURCE) }), + CATALOG, + )!, + }; + await expect( + fetchCatalogAppModule(app, serve(`${SOURCE}\n// tampered`)), + ).rejects.toThrow(/does not match the catalog/); + await expect(fetchCatalogAppModule(app, serve('', 404))).rejects.toThrow( + /could not be downloaded \(404\)/, + ); + }); +}); + +describe('versions', () => { + it('compares dotted numeric versions', () => { + expect(compareVersions('0.10.0', '0.9.1')).toBe(1); + expect(compareVersions('0.1.0', '0.1.0')).toBe(0); + expect(compareVersions('1.0.0-beta.1', '1.0.0')).toBe(-1); + expect(compareVersions('0.1', '0.1.0')).toBe(0); + }); + + it('offers install, update or nothing — never a downgrade', () => { + expect(catalogAppState({ version: '0.2.0' }, undefined)).toBe('install'); + expect(catalogAppState({ version: '0.2.0' }, { version: '0.1.0' })).toBe( + 'update', + ); + expect(catalogAppState({ version: '0.2.0' }, { version: '0.2.0' })).toBe( + 'current', + ); + expect(catalogAppState({ version: '0.2.0' }, { version: '0.3.0' })).toBe( + 'ahead', + ); + expect(catalogAppState({ version: '0.2.0' }, {})).toBe('update'); + }); +}); diff --git a/browser/lib/src/catalog-app.ts b/browser/lib/src/catalog-app.ts new file mode 100644 index 0000000000..50ffa0a952 --- /dev/null +++ b/browser/lib/src/catalog-app.ts @@ -0,0 +1,395 @@ +import { core } from './ontologies/core.js'; +import { dataBrowser } from './ontologies/dataBrowser.js'; +import { Datatype } from './datatypes.js'; +import { + createApp, + describeApp, + updateApp, + type AppDescription, + type CreatedApp, +} from './plugin-app.js'; +import { + ensureSchema, + findSchema, + type SchemaSpec, + type SchemaStore, +} from './plugin-schema.js'; + +/** + * Drive apps published in a plugin catalog (ontola/atomic-plugins + * `integrations/catalog.json`), installed as ordinary apps. + * + * A catalog entry names one built, immutable ES module for exactly one + * version, and the Subresource Integrity hash of its bytes. Installing fetches + * those bytes, refuses them unless the hash matches, and hands them to + * `createApp` as the entry point's source — the same app, ontology, table and + * identity the New menu makes. The app then records where it came from, so the + * catalog can say which version is installed and offer the next one. + * + * Updating is `updateApp`: only the entry point's source changes, so the app's + * rows, schema, identity and rights survive it. + */ + +const CATALOG = 'https://atomicdata.dev/integrations/properties/'; + +/** The catalog's own vocabulary for an app entry. */ +export const catalogAppProperties = { + shortname: core.properties.shortname, + name: core.properties.name, + description: core.properties.description, + emoji: dataBrowser.properties.emoji, + version: `${CATALOG}version`, + module: `${CATALOG}app-module`, + integrity: `${CATALOG}app-module-integrity`, + rowName: `${CATALOG}app-row-name`, + rowNamePlural: `${CATALOG}app-row-name-plural`, +} as const; + +/** One installable app, as a catalog entry describes it. */ +export interface CatalogApp { + /** The entry's shortname: stable across versions. */ + id: string; + name: string; + emoji?: string; + description?: string; + version: string; + /** Absolute URL of the module for exactly `version`. */ + module: string; + /** `sha256-`, `sha384-` or `sha512-` followed by base64, as in SRI. */ + integrity: string; + rowName?: { singular: string; plural: string }; +} + +const asString = (value: unknown): string | undefined => + typeof value === 'string' && value.trim().length > 0 ? value : undefined; + +const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']); + +/** + * Where a module may be fetched from: HTTPS, or HTTP on this machine for + * development. A relative URL is resolved against the catalog it came from. + */ +export function resolveModuleUrl(value: string, catalogUrl: string): string { + const url = new URL(value, catalogUrl); + + if ( + url.protocol !== 'https:' && + !(url.protocol === 'http:' && LOOPBACK.has(url.hostname)) + ) { + throw new Error(`An app module must be served over HTTPS: ${url.href}`); + } + + if (url.username || url.password) { + throw new Error('An app module URL cannot carry credentials'); + } + + return url.href; +} + +const INTEGRITY = /^(sha256|sha384|sha512)-[A-Za-z0-9+/]+={0,2}$/; + +/** + * Reads an app out of a catalog entry, or `undefined` for an entry that is not + * an installable app. Malformed app fields are skipped the same way, so one bad + * row cannot hide the rest of the catalog. + */ +export function parseCatalogApp( + entry: unknown, + catalogUrl: string, +): CatalogApp | undefined { + if (!entry || typeof entry !== 'object' || Array.isArray(entry)) { + return undefined; + } + + const values = entry as Record; + const p = catalogAppProperties; + const id = asString(values[p.shortname]); + const name = asString(values[p.name]); + const version = asString(values[p.version]); + const module = asString(values[p.module]); + const integrity = asString(values[p.integrity]); + + if (!id || !name || !version || !module || !integrity) return undefined; + if (!INTEGRITY.test(integrity)) return undefined; + + let resolved: string; + + try { + resolved = resolveModuleUrl(module, catalogUrl); + } catch { + return undefined; + } + + const singular = asString(values[p.rowName]); + const plural = asString(values[p.rowNamePlural]); + + return { + id, + name, + version, + module: resolved, + integrity, + emoji: asString(values[p.emoji]), + description: asString(values[p.description]), + rowName: singular && plural ? { singular, plural } : undefined, + }; +} + +const ALGORITHMS = { + sha256: 'SHA-256', + sha384: 'SHA-384', + sha512: 'SHA-512', +} as const; + +function base64(bytes: Uint8Array): string { + let binary = ''; + + for (const byte of bytes) binary += String.fromCharCode(byte); + + return btoa(binary); +} + +/** The SRI string (`sha384-…`) for `text`'s UTF-8 bytes. */ +export async function subresourceIntegrity( + text: string, + algorithm: keyof typeof ALGORITHMS = 'sha384', +): Promise { + const digest = await crypto.subtle.digest( + ALGORITHMS[algorithm], + new TextEncoder().encode(text), + ); + + return `${algorithm}-${base64(new Uint8Array(digest))}`; +} + +/** Four megabytes: the same ceiling an app package gets. */ +const MAX_MODULE_BYTES = 4 * 1024 * 1024; + +/** + * Fetches an app's module and returns its text, or throws unless its bytes + * match the integrity the catalog pinned. + * + * Nothing is evaluated here: the text is only ever stored, and runs later in + * the app's own null-origin frame. + */ +export async function fetchCatalogAppModule( + app: Pick, + transport: typeof fetch = fetch, +): Promise { + const response = await transport(app.module, { credentials: 'omit' }); + + if (!response.ok) { + throw new Error( + `${app.name} ${app.version} could not be downloaded (${response.status}) from ${app.module}`, + ); + } + + const text = await response.text(); + + if (new TextEncoder().encode(text).length > MAX_MODULE_BYTES) { + throw new Error(`${app.name} ${app.version} is larger than 4 MiB`); + } + + const algorithm = app.integrity.split('-')[0] as keyof typeof ALGORITHMS; + + if (!(algorithm in ALGORITHMS)) { + throw new Error(`Unsupported integrity algorithm: ${algorithm}`); + } + + const actual = await subresourceIntegrity(text, algorithm); + + if (actual !== app.integrity) { + throw new Error( + `${app.name} ${app.version} does not match the catalog: expected ${app.integrity}, got ${actual}. Nothing was installed.`, + ); + } + + return text; +} + +/** + * Where an installed app says it came from. Drive-local, like the rest of the + * app vocabulary (`pluginSchema`), so it needs no change to the core ontology. + */ +export function catalogAppSchema(): SchemaSpec { + return { + properties: [ + { + shortname: 'app-catalog-id', + name: 'Catalog entry', + description: + 'The catalog entry (its shortname) this app was installed from. Apps made by hand have none.', + datatype: Datatype.STRING, + }, + { + shortname: 'app-version', + name: 'Installed version', + description: + "The catalog version whose module is this app's entry point. Compared against the catalog to offer an update.", + datatype: Datatype.STRING, + }, + { + shortname: 'app-module', + name: 'Module URL', + description: 'Where the installed module was downloaded from.', + datatype: Datatype.STRING, + }, + { + shortname: 'app-module-integrity', + name: 'Module integrity', + description: + 'The Subresource Integrity hash the installed module was checked against.', + datatype: Datatype.STRING, + }, + ], + classes: [], + }; +} + +async function recordProvenance( + store: SchemaStore, + drive: string, + subject: string, + app: CatalogApp, +): Promise { + const schema = await ensureSchema(store, drive, catalogAppSchema()); + const resource = await store.getResource(subject); + await resource.set(schema.properties['app-catalog-id'], app.id); + await resource.set(schema.properties['app-version'], app.version); + await resource.set(schema.properties['app-module'], app.module); + await resource.set(schema.properties['app-module-integrity'], app.integrity); + await resource.save(); +} + +/** + * Installs a catalog app into `drive`: downloads and verifies its module, then + * creates the app, its ontology, row class, table, entry point and identity + * through `createApp`. The returned secret is the app agent's, as from + * `createApp`; the caller decides where it goes (the data-browser hands it to + * the node). + */ +export async function installCatalogApp( + store: SchemaStore, + options: { drive: string; app: CatalogApp; transport?: typeof fetch }, +): Promise { + const { drive, app } = options; + const source = await fetchCatalogAppModule(app, options.transport); + const created = await createApp(store, { + drive, + name: app.name, + emoji: app.emoji, + description: app.description, + rowName: app.rowName, + source, + }); + await recordProvenance(store, drive, created.app, app); + + return created; +} + +/** + * Moves an installed app to the catalog's version. Only the entry point's + * source and the provenance change; rows, schema, identity and rights stay. + */ +export async function updateCatalogApp( + store: SchemaStore, + options: { + drive: string; + subject: string; + app: CatalogApp; + transport?: typeof fetch; + }, +): Promise { + const { drive, subject, app } = options; + const source = await fetchCatalogAppModule(app, options.transport); + await updateApp(store, drive, { app: subject, source }); + await recordProvenance(store, drive, subject, app); + + return describeApp(store, drive, subject); +} + +/** An app on the drive that came from a catalog. */ +export interface InstalledCatalogApp { + subject: string; + id: string; + version?: string; +} + +/** + * The catalog apps installed on `drive`, found by their `app-catalog-id`. + * `list` lists every resource on the drive carrying a property (the host's + * `/query`, e.g. `readConnectionSubjects`). Read-only: a drive that never + * installed one has no such property and yields nothing. + */ +export async function readInstalledCatalogApps( + store: SchemaStore, + drive: string, + list: (property: string) => Promise, +): Promise { + const schema = await findSchema(store, drive, catalogAppSchema()); + const idProp = schema.properties?.['app-catalog-id']; + const versionProp = schema.properties?.['app-version']; + + if (!idProp) return []; + + const found: InstalledCatalogApp[] = []; + + for (const subject of await list(idProp)) { + const resource = await store.getResource(subject); + const id = asString(resource.get(idProp)); + if (!id) continue; + found.push({ + subject, + id, + version: versionProp ? asString(resource.get(versionProp)) : undefined, + }); + } + + return found; +} + +/** + * Compares dotted numeric versions (`0.10.0` > `0.9.1`). A pre-release suffix + * (`-beta.1`) sorts before its release. Anything unparseable compares by string. + */ +export function compareVersions(a: string, b: string): number { + const parse = (v: string) => { + const [core_, pre] = v.split('-', 2); + + return { parts: core_.split('.').map(Number), pre }; + }; + + const x = parse(a); + const y = parse(b); + + if ([...x.parts, ...y.parts].some(n => !Number.isInteger(n))) { + return a.localeCompare(b); + } + + for (let i = 0; i < Math.max(x.parts.length, y.parts.length); i++) { + const d = (x.parts[i] ?? 0) - (y.parts[i] ?? 0); + if (d !== 0) return Math.sign(d); + } + + if (x.pre === y.pre) return 0; + if (x.pre === undefined) return 1; + if (y.pre === undefined) return -1; + + return x.pre.localeCompare(y.pre); +} + +/** + * What the catalog should offer for `app` given what is installed: install it, + * nothing (current, or newer than the catalog — never a downgrade), or an + * update to the catalog's version. + */ +export function catalogAppState( + app: Pick, + installed: Pick | undefined, +): 'install' | 'current' | 'update' | 'ahead' { + if (!installed) return 'install'; + if (!installed.version) return 'update'; + const order = compareVersions(app.version, installed.version); + + return order > 0 ? 'update' : order < 0 ? 'ahead' : 'current'; +} diff --git a/browser/lib/src/index.ts b/browser/lib/src/index.ts index 94d70eabf4..5791e48a5f 100644 --- a/browser/lib/src/index.ts +++ b/browser/lib/src/index.ts @@ -191,6 +191,21 @@ export { type CreateAppOptions, type CreatedApp, } from './plugin-app.js'; +export { + catalogAppProperties, + catalogAppSchema, + catalogAppState, + compareVersions, + fetchCatalogAppModule, + installCatalogApp, + parseCatalogApp, + readInstalledCatalogApps, + resolveModuleUrl, + subresourceIntegrity, + updateCatalogApp, + type CatalogApp, + type InstalledCatalogApp, +} from './catalog-app.js'; export { parseManifest, validateManifest,