From 6cfad82c1ba1db88c5f39731c75181b5aed63448 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 24 Sep 2026 16:59:59 +0200 Subject: [PATCH 1/8] localthought: mock proxy speaks integration-proxy 0.2 (#54 phase 2) The e2e mock proxy now checks what the real proxy (integration-proxy/src, #122) checks on the surface a client sees: Atomic v2 request signatures (method, full URL under the mock's BASE_URL, timestamp, body hash; +-5 min; single use), agent ids in both prefixes and alphabets, frame capabilities (owner-signed, aud, exp <= 15 min, scope, delegation, cnf signs the request), connections owned by the redeem signer, delegations, runtimes, and the proxy's {error, message} codes. No login and no user_id at /connect; API-key platforms take the key on the consent page, as templates.rs does. Rotating connection codes, Bearer and X-Connection-Code are gone. Fixtures, their drivers (/__fixture/..., /fixture//) and failure injection are unchanged: the mock rewrites /proxy/{id}/{platform}/ to the /proxy/{platform}/ paths fixtures already match. New test-side introspection: GET /__mock/connections and POST /__mock/revoke. mock-proxy.test.mjs verifies the shared v2 vectors (integration-proxy/tests/fixtures/atomic-request-v2-vectors.json) and atomic-server's capability vector against the mock's verifier. Kept the mock rather than running the real binary: the real proxy only accepts https upstreams and catalogs, needs a provider OAuth server per platform and Postgres per lane. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 10 +- integrations/localthought/browser-smoke.mjs | 65 -- integrations/localthought/browser.test.ts | 265 ------ integrations/localthought/browser.ts | 272 ------ integrations/localthought/mock-proxy-auth.mjs | 320 +++++++ integrations/localthought/mock-proxy.d.mts | 27 +- integrations/localthought/mock-proxy.mjs | 619 ++++++++++-- integrations/localthought/mock-proxy.test.mjs | 892 ++++++++++++++---- integrations/localthought/settings.test.ts | 105 --- integrations/localthought/settings.ts | 81 -- 10 files changed, 1607 insertions(+), 1049 deletions(-) delete mode 100644 integrations/localthought/browser-smoke.mjs delete mode 100644 integrations/localthought/browser.test.ts delete mode 100644 integrations/localthought/browser.ts create mode 100644 integrations/localthought/mock-proxy-auth.mjs delete mode 100644 integrations/localthought/settings.test.ts delete mode 100644 integrations/localthought/settings.ts diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 828560c79..b5e1b23ba 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,8 +34,9 @@ name: CI # dev-server.mjs for why it no longer proxies). # - `integrations/localthought/mock-proxy.mjs` (the same fixture # atomic-server's own dagger e2e pipeline runs) stands in for the real -# LocalThought integration proxy, so the Integrations-page flow can run -# without live provider credentials. +# integration proxy (`integration-proxy/`): it checks the proxy's 0.2 +# signatures, capabilities and delegations the same way, with +# per-platform provider fixtures instead of live credentials. # # ## Job graph # @@ -68,9 +69,8 @@ name: CI # # No Rust/WASM tests run here: not the sandboxTests declared in each # package's atomicCertification (those are atomic-server's own `cargo test` -# suite, run by its CI), and not localthought's browser-smoke.mjs (it -# needs a full Vite app). Building the atomic-server binary itself is unavoidable -# infrastructure, not a test. +# suite, run by its CI). Building the atomic-server binary itself is +# unavoidable infrastructure, not a test. on: pull_request: diff --git a/integrations/localthought/browser-smoke.mjs b/integrations/localthought/browser-smoke.mjs deleted file mode 100644 index 8d53b844e..000000000 --- a/integrations/localthought/browser-smoke.mjs +++ /dev/null @@ -1,65 +0,0 @@ -/** Run against Vite + the mock proxy, with VITE_ATOMIC_SERVER_URL on a closed port. */ -import { chromium } from '../../browser/e2e/node_modules/@playwright/test/index.mjs'; -const browser = await chromium.launch({ headless: true }); -const page = await browser.newPage(); -page.setDefaultTimeout(45000); -await page.route('http://127.0.0.1:19999/**', route => route.abort()); -const errors = []; -page.on('pageerror', e => errors.push(e.message)); - -try { - console.log('Opening offline dev drive'); - await page.goto('http://localhost:6748/app/dev-drive'); - await page.waitForURL(/app\/show\?subject=/, { timeout: 120000 }); - console.log('Opening integrations'); - await page.getByRole('link', { name: 'Integrations', exact: true }).click(); - console.log('Opening Pets'); - const pets = page.locator('[data-integration="proxy:pets"]'); - await pets.getByRole('button', { name: 'Set up connection' }).click(); - await page - .getByRole('button', { name: 'Install and connect', exact: true }) - .click(); - await page - .getByRole('button', { - name: 'Use LocalThought to sync Pets with your Atomic Data Hub', - exact: true, - }) - .click(); - console.log('Installing and opening folder'); - await page.getByRole('button', { name: 'Complete installation' }).click(); - await page.getByRole('link', { name: 'Open folder', exact: true }).click(); - await page.getByRole('status').filter({ hasText: 'Last synced' }).waitFor(); - await page - .locator('[data-test="folder-list"]') - .getByRole('link', { name: 'Pets', exact: true }) - .click(); - for (const name of ['Rex', 'Whiskers', 'Tweety', 'Nibbles', 'Bubbles']) - await page - .getByRole('main') - .getByText(name, { exact: true }) - .first() - .waitFor(); - await page.reload(); - for (const name of ['Rex', 'Whiskers', 'Tweety', 'Nibbles', 'Bubbles']) - await page - .getByRole('main') - .getByText(name, { exact: true }) - .first() - .waitFor(); - console.log( - 'Browser-only OAuth, background WASM import, OPFS apply and reload passed', - ); -} catch (error) { - console.error( - error.message, - '\nURL:', - page.url(), - '\nUI:', - (await page.locator('body').innerText()).slice(-7000), - '\nErrors:', - errors, - ); - process.exitCode = 1; -} finally { - await browser.close(); -} diff --git a/integrations/localthought/browser.test.ts b/integrations/localthought/browser.test.ts deleted file mode 100644 index 3c7f04cdc..000000000 --- a/integrations/localthought/browser.test.ts +++ /dev/null @@ -1,265 +0,0 @@ -import { afterEach, expect, it, vi } from 'vitest'; -import { BrowserIntegrations, proxyOrigin } from './browser'; -const origin = 'https://proxy.example'; - -function setup() { - const values = new Map(); - const storage = { - getItem: (k: string) => values.get(k) ?? null, - setItem: (k: string, v: string) => { - values.set(k, v); - }, - removeItem: (k: string) => { - values.delete(k); - }, - } as Storage; - vi.stubGlobal('location', { origin: 'https://atomic.example' }); - vi.stubGlobal('navigator', { - locks: { request: (_: string, f: () => unknown) => f() }, - }); - const http = vi.fn(async (url: string, init?: RequestInit) => { - expect(init?.credentials).toBe('omit'); - expect(init?.redirect).toBe('error'); - if (url.endsWith('/catalog')) return new Response('["pets"]'); - if (url.endsWith('/connect/redeem')) - return Response.json({ connection_code: 'first', platform: 'pets' }); - - return new Response('{}'); - }); - const client = new BrowserIntegrations(storage, origin, http as typeof fetch); - const start = () => - client.start( - 'drive', - 'actor', - 'pets', - 'https://atomic.example/app/integrations', - ); - - return { values, storage, http, client, start }; -} - -afterEach(() => { - vi.unstubAllGlobals(); - vi.restoreAllMocks(); -}); -it('rejects non-origin proxy URLs', () => { - expect(() => proxyOrigin('https://proxy.example/path')).toThrow(); - expect(() => proxyOrigin('http://proxy.example')).toThrow(); -}); -it('starts a platform-bound PKCE redirect without a tenant session', async () => { - const { start, values, http } = setup(); - const { state, url } = await start(); - const redirect = new URL(url); - const callback = new URL(redirect.searchParams.get('redirect_uri')!); - const pending = JSON.parse([...values.values()][0]); - const digest = await crypto.subtle.digest( - 'SHA-256', - new TextEncoder().encode(pending.codeVerifier), - ); - const expectedChallenge = btoa(String.fromCharCode(...new Uint8Array(digest))) - .replaceAll('+', '-') - .replaceAll('/', '_') - .replaceAll('=', ''); - - expect(redirect.pathname).toBe('/connect'); - expect(Object.fromEntries(redirect.searchParams)).toEqual({ - platform: 'pets', - redirect_uri: callback.href, - user_id: 'actor', - code_challenge: expectedChallenge, - code_challenge_method: 'S256', - credentials: 'connection', - }); - expect(callback.searchParams.get('integration_state')).toBe(state); - expect(callback.searchParams.get('platform')).toBe('pets'); - expect(pending.codeVerifier).toMatch(/^[A-Za-z0-9_-]{43}$/); - expect( - http.mock.calls.some(([request]) => String(request).endsWith('/session')), - ).toBe(false); -}); -it('binds redemption to actor, drive, platform and expiry', async () => { - const { client, start, values, http } = setup(); - const { state } = await start(); - await expect( - client.finish('other', 'actor', state, 'code'), - ).rejects.toThrow(); - await expect( - client.finish('drive', 'other', state, 'code'), - ).rejects.toThrow(); - http.mockImplementationOnce(async (_url, init) => { - const pending = JSON.parse([...values.values()][0]); - expect(pending.codeVerifier).toBeUndefined(); - expect(init).toMatchObject({ - method: 'POST', - body: expect.any(String), - credentials: 'omit', - redirect: 'error', - }); - expect(JSON.parse(init!.body as string)).toEqual({ - code: 'code', - code_verifier: expect.stringMatching(/^[A-Za-z0-9_-]{43}$/), - }); - - return Response.json({ connection_code: 'first', platform: 'pets' }); - }); - await expect(client.finish('drive', 'actor', state, 'code')).resolves.toEqual( - { - connection: state, - platform: 'pets', - }, - ); - expect(JSON.parse([...values.values()][0])).toMatchObject({ - platform: 'pets', - ready: true, - code: 'first', - }); - expect(JSON.parse([...values.values()][0]).codeVerifier).toBeUndefined(); - await expect( - client.finish('drive', 'actor', state, 'code'), - ).rejects.toThrow(); -}); -it('does not save a credential when redemption returns another platform', async () => { - const { client, start, values, http } = setup(); - const { state } = await start(); - http.mockImplementationOnce(async () => - Response.json({ connection_code: 'first', platform: 'github-issues' }), - ); - await expect(client.finish('drive', 'actor', state, 'code')).rejects.toThrow( - 'platform', - ); - expect(JSON.parse([...values.values()][0])).toMatchObject({ ready: false }); - expect(JSON.parse([...values.values()][0]).code).toBeUndefined(); -}); -it('clears expired and denied pending verifiers', async () => { - const { client, start, values, http } = setup(); - const expired = await start(); - const [expiredKey, expiredValue] = [...values.entries()][0]; - values.set( - expiredKey, - JSON.stringify({ ...JSON.parse(expiredValue), expires: Date.now() - 1 }), - ); - await expect( - client.finish('drive', 'actor', expired.state, 'code'), - ).rejects.toThrow('Reconnect'); - expect(values.has(expiredKey)).toBe(false); - - const denied = await start(); - client.cancel('drive', 'actor', denied.state); - expect([...values.values()]).toHaveLength(0); - expect( - http.mock.calls.some(([request]) => String(request).endsWith('/redeem')), - ).toBe(false); -}); -it('never retries an uncertain redemption after consuming its verifier', async () => { - const { client, start, http } = setup(); - const { state } = await start(); - http.mockImplementationOnce(async () => { - throw new Error('connection lost'); - }); - await expect(client.finish('drive', 'actor', state, 'code')).rejects.toThrow( - 'lost', - ); - const calls = http.mock.calls.length; - await expect(client.finish('drive', 'actor', state, 'code')).rejects.toThrow( - 'Reconnect', - ); - expect(http.mock.calls).toHaveLength(calls); -}); -it('consumes before dispatch and preserves rotation', async () => { - const { client, start, http, values } = setup(); - const { state } = await start(); - await client.finish('drive', 'actor', state, 'handoff'); - const codes: string[] = []; - http.mockImplementation(async (_url, init) => { - expect(JSON.parse([...values.values()][0]).code).toBeUndefined(); - codes.push((init!.headers as Record).Authorization); - - return new Response('[]', { - headers: { 'x-connection-code': 'second' }, - }); - }); - await client.request('drive', 'actor', state, 'pets', '/pets'); - expect(codes).toEqual(['Bearer first']); -}); -it('never retries an uncertain consumed credential', async () => { - const { client, start, http } = setup(); - const { state } = await start(); - await client.finish('drive', 'actor', state, 'handoff'); - http.mockImplementation(async () => { - throw new Error('connection lost'); - }); - await expect( - client.request('drive', 'actor', state, 'pets', '/pets'), - ).rejects.toThrow('lost'); - const calls = http.mock.calls.length; - await expect( - client.request('drive', 'actor', state, 'pets', '/pets'), - ).rejects.toThrow('Reconnect'); - expect(http.mock.calls).toHaveLength(calls); -}); - -it('calls the browser fetch function without binding it to the client', async () => { - const { storage } = setup(); - vi.stubGlobal('fetch', function (this: unknown) { - expect(this).not.toBeInstanceOf(BrowserIntegrations); - - return Promise.resolve(new Response('["pets"]')); - }); - const client = new BrowserIntegrations(storage, origin); - expect(await client.catalog()).toEqual(['pets']); -}); - -it('supports the demo callback and write credentials', async () => { - const { client, http, values } = setup(); - const { state } = await client.start( - 'drive', - 'actor', - 'pets', - 'https://atomic.example/app/devonian-demo', - ); - await client.finish('drive', 'actor', state, 'handoff'); - http.mockImplementation(async (_url, init) => { - expect(JSON.parse([...values.values()][0]).code).toBeUndefined(); - expect(init?.method).toBe('POST'); - expect(init?.body).toBe('{"title":"new"}'); - - return new Response('{"id":1}', { - status: 201, - headers: { 'X-Connection-Code': 'next' }, - }); - }); - await expect( - client.request('drive', 'actor', state, 'github-issues', '/issues'), - ).rejects.toThrow('another platform'); - await expect( - client.request('drive', 'actor', state, 'pets', '//evil.example'), - ).rejects.toThrow('Invalid proxy path'); - expect( - await client.request('drive', 'actor', state, 'pets', '/issues', { - method: 'POST', - body: '{"title":"new"}', - }), - ).toEqual({ status: 201, body: '{"id":1}' }); - expect(JSON.parse([...values.values()][0]).code).toBe('next'); -}); -it('forwards the conditional event version while keeping authorization host-owned', async () => { - const { client, start, http } = setup(); - const { state } = await start(); - await client.finish('drive', 'actor', state, 'handoff'); - http.mockImplementation(async (_url, init) => { - expect(init?.headers).toEqual({ - Authorization: 'Bearer first', - 'Content-Type': 'application/json', - 'If-Match': '"version"', - }); - expect(init?.method).toBe('PATCH'); - expect(init?.body).toBe('{"summary":"Updated"}'); - - return new Response('{}', { headers: { 'x-connection-code': 'next' } }); - }); - await client.request('drive', 'actor', state, 'pets', '/events/id', { - method: 'PATCH', - body: '{"summary":"Updated"}', - ifMatch: '"version"', - }); -}); diff --git a/integrations/localthought/browser.ts b/integrations/localthought/browser.ts deleted file mode 100644 index 646ff28f2..000000000 --- a/integrations/localthought/browser.ts +++ /dev/null @@ -1,272 +0,0 @@ -/** Browser-owned credentials. Never store these in Atomic graph resources. */ -export const DEFAULT_PROXY = 'https://localthought.io'; -const key = 'localthought-browser-v1:'; - -export interface Connection { - drive: string; - actor: string; - platform: string; - origin: string; - expires: number; - code?: string; - codeVerifier?: string; - ready: boolean; -} -export function proxyOrigin(value = DEFAULT_PROXY): string { - const u = new URL(value); - if ( - u.origin !== value || - (u.protocol !== 'https:' && - !( - u.protocol === 'http:' && - ['localhost', '127.0.0.1'].includes(u.hostname) - )) - ) - throw new Error('Proxy must be an HTTPS origin or localhost'); - - return value; -} - -const base64url = (bytes: Uint8Array) => - btoa(String.fromCharCode(...bytes)) - .replaceAll('+', '-') - .replaceAll('/', '_') - .replaceAll('=', ''); - -async function limitedText(response: Response): Promise { - if (!response.body) throw new Error('Empty proxy response'); - const reader = response.body.getReader(); - const decoder = new TextDecoder(); - let size = 0, - text = ''; - - try { - for (;;) { - const { done, value } = await reader.read(); - if (done) break; - size += value.byteLength; - if (size > 10 * 1024 * 1024) - throw new Error('Proxy response exceeds 10 MB'); - text += decoder.decode(value, { stream: true }); - } - - return text + decoder.decode(); - } finally { - await reader.cancel(); - } -} - -export class BrowserIntegrations { - constructor( - private storage: Storage, - readonly origin = DEFAULT_PROXY, - private http: typeof fetch = (...args) => fetch(...args), - ) { - proxyOrigin(origin); - } - private async get(path: string, signal?: AbortSignal) { - const response = await this.http(`${this.origin}${path}`, { - credentials: 'omit', - redirect: 'error', - signal: signal ?? AbortSignal.timeout(30000), - }); - if (!response.ok) - throw new Error(`LocalThought returned HTTP ${response.status}`); - - return limitedText(response); - } - async catalog(signal?: AbortSignal): Promise { - const names = JSON.parse(await this.get('/catalog', signal)); - if ( - !Array.isArray(names) || - names.length > 200 || - names.some(s => typeof s !== 'string' || !/^[a-z0-9-]{1,80}$/.test(s)) - ) - throw new Error('Invalid platform catalog'); - - return names; - } - async start( - drive: string, - actor: string, - platform: string, - returnUrl: string, - ) { - if (!(await this.catalog()).includes(platform)) - throw new Error('Unknown platform'); - const callback = new URL(returnUrl); - if ( - callback.origin !== location.origin || - !['/app/integrations', '/app/devonian-demo'].includes( - callback.pathname, - ) || - callback.search || - callback.hash - ) - throw new Error('Invalid integration return URL'); - const state = base64url(crypto.getRandomValues(new Uint8Array(32))); - const codeVerifier = base64url(crypto.getRandomValues(new Uint8Array(32))); - const codeChallenge = base64url( - new Uint8Array( - await crypto.subtle.digest( - 'SHA-256', - new TextEncoder().encode(codeVerifier), - ), - ), - ); - callback.searchParams.set('integration_state', state); - callback.searchParams.set('platform', platform); - const url = new URL(`${this.origin}/connect`); - for (const [k, v] of Object.entries({ - platform, - redirect_uri: callback.href, - user_id: actor, - code_challenge: codeChallenge, - code_challenge_method: 'S256', - credentials: 'connection', - })) - url.searchParams.set(k, v as string); - // Only the short-lived PKCE handoff survives navigation. - this.storage.setItem( - key + state, - JSON.stringify({ - drive, - actor, - platform, - origin: this.origin, - expires: Date.now() + 600000, - codeVerifier, - ready: false, - } satisfies Connection), - ); - - return { state, url: url.href }; - } - private connection(id: string, drive: string, actor: string) { - const raw = this.storage.getItem(key + id); - if (!raw) throw new Error('Reconnect your account'); - const c: Connection = JSON.parse(raw); - if (c.drive !== drive || c.actor !== actor || c.origin !== this.origin) - throw new Error('Connection belongs to another drive, agent or proxy'); - - return c; - } - cancel(drive: string, actor: string, state: string) { - this.connection(state, drive, actor); - this.storage.removeItem(key + state); - } - async finish(drive: string, actor: string, state: string, code: string) { - const c = this.connection(state, drive, actor); - - if (c.expires < Date.now()) { - this.storage.removeItem(key + state); - throw new Error('Reconnect your account'); - } - - if (c.ready || !c.codeVerifier || !code || code.length > 4096) - throw new Error('Reconnect your account'); - const verifier = c.codeVerifier; - delete c.codeVerifier; - // Consume before dispatch: a lost response may have spent the handoff code. - this.storage.setItem(key + state, JSON.stringify(c)); - const response = await this.http(`${this.origin}/connect/redeem`, { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ code, code_verifier: verifier }), - credentials: 'omit', - redirect: 'error', - signal: AbortSignal.timeout(30000), - }); - if (!response.ok) - throw new Error(`LocalThought returned HTTP ${response.status}`); - const result = JSON.parse(await limitedText(response)) as { - connection_code?: unknown; - platform?: unknown; - }; - if (result.platform !== c.platform) - throw new Error('Returned platform did not match the requested platform'); - if ( - typeof result.connection_code !== 'string' || - !result.connection_code || - result.connection_code.length > 4096 - ) - throw new Error('LocalThought returned an invalid connection code'); - this.storage.setItem( - key + state, - JSON.stringify({ ...c, ready: true, code: result.connection_code }), - ); - - return { connection: state, platform: c.platform }; - } - /** Shared rotating-code transport for browser-owned writes as well as reads. */ - async request( - drive: string, - actor: string, - id: string, - platform: string, - path: string, - init: { method?: string; body?: string; ifMatch?: string } = {}, - ): Promise<{ status: number; body: string }> { - if (!navigator.locks) - throw new Error('This browser needs Web Locks for integrations'); - if (!path.startsWith('/') || path.startsWith('//') || /[\\\\#]/.test(path)) - throw new Error('Invalid proxy path'); - const destination = new URL(`/proxy/${platform}${path}`, this.origin); - if (!destination.pathname.startsWith(`/proxy/${platform}/`)) - throw new Error('Invalid proxy path'); - - return navigator.locks.request(key + id, async () => { - const c = this.connection(id, drive, actor); - if (c.platform !== platform) - throw new Error('Connection belongs to another platform'); - const response = await this.send( - id, - drive, - actor, - path, - init, - AbortSignal.timeout(30000), - ); - - return { status: response.status, body: await limitedText(response) }; - }); - } - private async send( - id: string, - drive: string, - actor: string, - path: string, - init: { method?: string; body?: string; ifMatch?: string }, - signal: AbortSignal, - ) { - const current = this.connection(id, drive, actor); - if (!current.ready || !current.code) - throw new Error('Reconnect before retrying an uncertain request'); - const code = current.code; - delete current.code; - this.storage.setItem(key + id, JSON.stringify(current)); - const response = await this.http( - `${this.origin}/proxy/${current.platform}${path}`, - { - method: init.method, - body: init.body, - headers: { - Authorization: `Bearer ${code}`, - 'Content-Type': 'application/json', - ...(init.ifMatch ? { 'If-Match': init.ifMatch } : {}), - }, - credentials: 'omit', - redirect: 'error', - signal, - }, - ); - const next = response.headers.get('x-connection-code'); - if (!next) - throw new Error( - 'Proxy did not expose a rotated code; reconnect and check CORS', - ); - this.storage.setItem(key + id, JSON.stringify({ ...current, code: next })); - - return response; - } -} diff --git a/integrations/localthought/mock-proxy-auth.mjs b/integrations/localthought/mock-proxy-auth.mjs new file mode 100644 index 000000000..695473e27 --- /dev/null +++ b/integrations/localthought/mock-proxy-auth.mjs @@ -0,0 +1,320 @@ +/** + * The integration proxy's 0.2 authentication (ontola/atomic-plugins#54), for + * the local-only mock (`mock-proxy.mjs`) and its tests. Never deploy this. + * + * It re-implements, in plain Node, exactly what `integration-proxy/src/` + * checks on the surface a client sees: + * + * - agent ids (`agent_id.rs`): `atomic:agent:` or `did:ad:agent:`, + * the key base64 in either alphabet, padded or not, 32 bytes (Ed25519); + * canonical form `atomic:agent:`; + * - version 2 request signatures (`signature.rs`): five `\n`-joined lines + * `atomic-request-v2`, METHOD, full URL, timestamp (Unix ms), lowercase + * hex SHA-256 of the body; ±5 min skew; the version header must be `2`; + * - frame capabilities (`capability.rs`): `Capability .`, + * payload base64url of the JSON claims, `sig` by the connection owner over + * `integration-proxy-capability-v2\n` + those JSON bytes, exact claim set, + * `exp` in Unix seconds at most 15 min ahead; + * - error codes and messages (`api_error.rs`). + * + * The shared golden vectors (`integration-proxy/tests/fixtures/ + * atomic-request-v2-vectors.json`, a copy of atomic-server's + * `lib/src/authentication_v2_vectors.json`) are checked against this file in + * `mock-proxy.test.mjs`, so the mock and both real implementations agree. + * + * `testSigner` and `mintCapability` are the client side, for tests only; in + * the e2e the data browser page and the plugin frame sign for real. + */ +import { + createHash, + createPrivateKey, + createPublicKey, + sign as edSign, + verify as edVerify, +} from 'node:crypto'; + +export const AGENT_HEADER = 'x-atomic-agent'; +export const PUBLIC_KEY_HEADER = 'x-atomic-public-key'; +export const TIMESTAMP_HEADER = 'x-atomic-timestamp'; +export const SIGNATURE_HEADER = 'x-atomic-signature'; +export const VERSION_HEADER = 'x-atomic-signature-version'; +export const REQUEST_DOMAIN = 'atomic-request-v2'; +export const CAPABILITY_DOMAIN = 'integration-proxy-capability-v2'; +/** `signature::MAX_SKEW_MS`. */ +export const MAX_SKEW_MS = 5 * 60 * 1000; +/** `capability::MAX_LIFETIME_SECS`. */ +export const MAX_CAPABILITY_SECS = 15 * 60; + +/** `api_error.rs`: code -> [status, message]. */ +export const ERRORS = { + missing_signature: [ + 401, + 'this endpoint requires an Atomic v2 request signature (x-atomic-agent, x-atomic-public-key, x-atomic-timestamp, x-atomic-signature)', + ], + unsupported_signature_version: [401, 'x-atomic-signature-version must be 2'], + invalid_agent: [ + 401, + 'x-atomic-agent or x-atomic-public-key is not a valid atomic:agent id', + ], + agent_key_mismatch: [ + 401, + 'x-atomic-agent is not the agent of x-atomic-public-key', + ], + stale_timestamp: [ + 401, + "x-atomic-timestamp is missing, malformed, or more than 5 minutes from the proxy's clock", + ], + bad_signature: [ + 401, + 'x-atomic-signature does not verify over the atomic-request-v2 message', + ], + replayed: [401, 'this signed request was already used'], + invalid_capability: [ + 401, + "the capability is malformed or not signed by the connection's owner", + ], + capability_expired: [401, 'the capability has expired; request a new one'], + capability_too_long: [ + 401, + 'the capability is valid for more than 15 minutes', + ], + wrong_audience: [401, 'the capability is for a different proxy'], + capability_key_mismatch: [ + 401, + "the request is not signed by the capability's cnf key", + ], + unsupported_authorization: [ + 401, + 'the only Authorization scheme accepted is Capability; connection codes (Bearer) were retired', + ], + not_owner: [403, "only the connection's owner may do this"], + not_delegated: [ + 403, + 'the signing agent has no delegation for this connection', + ], + capability_scope: [ + 403, + 'the capability is for a different connection or platform', + ], + platform_mismatch: [403, 'the connection is for a different platform'], + unknown_connection: [ + 404, + 'no such connection; it was deleted, expired after 90 idle days, or never existed', + ], + invalid_handoff: [400, 'invalid or expired connection code'], +}; + +/** A refusal with one of the codes above; `message` overrides for `bad_request`. */ +export class ProxyRefusal extends Error { + constructor(code, message) { + const [status, text] = ERRORS[code] ?? [400, message ?? code]; + super(message ?? text); + this.code = code; + this.status = status; + } +} + +const B64 = /^[A-Za-z0-9+/_-]+={0,2}$/; + +/** Base64 in either alphabet, padded or not; `undefined` when malformed. */ +export function decodeB64(value) { + if (typeof value !== 'string' || !B64.test(value)) return undefined; + const bytes = Buffer.from( + value.replaceAll('-', '+').replaceAll('_', '/'), + 'base64', + ); + // Node skips what it cannot decode; a round trip catches a bad length. + const again = bytes.toString('base64').replace(/=+$/, ''); + if ( + again !== value.replaceAll('-', '+').replaceAll('_', '/').replace(/=+$/, '') + ) + return undefined; + + return bytes; +} + +export const b64url = bytes => Buffer.from(bytes).toString('base64url'); + +/** `agent_id::parse`: the canonical `atomic:agent:` id, or `undefined`. */ +export function parseAgent(id) { + if (typeof id !== 'string') return undefined; + const match = /^(?:atomic:agent:|did:ad:agent:)(.+)$/.exec(id); + if (!match) return undefined; + + return agentFromPublicKey(match[1]); +} + +/** `agent_id::from_public_key`. */ +export function agentFromPublicKey(key) { + const bytes = decodeB64(key); + if (!bytes || bytes.length !== 32) return undefined; + + return `atomic:agent:${b64url(bytes)}`; +} + +const publicKeyOf = canonical => + createPublicKey({ + key: { + kty: 'OKP', + crv: 'Ed25519', + x: canonical.slice('atomic:agent:'.length), + }, + format: 'jwk', + }); + +/** Ed25519 over `message` (bytes) by the canonical agent `agent`. */ +export function verifyBy(agent, message, signature) { + const sig = decodeB64(signature); + if (!sig || sig.length !== 64) return false; + + try { + return edVerify(null, Buffer.from(message), publicKeyOf(agent), sig); + } catch { + return false; + } +} + +export const sha256Hex = bytes => + createHash('sha256').update(bytes).digest('hex'); + +/** `signature::message`. */ +export function requestMessage(method, url, timestamp, body = '') { + return [ + REQUEST_DOMAIN, + method.toUpperCase(), + url, + String(timestamp), + sha256Hex(Buffer.from(body)), + ].join('\n'); +} + +/** + * `signature::verify`: returns `{ agent, replayKey }` or throws a + * `ProxyRefusal`. The caller spends `replayKey` (single use). + */ +export function verifyRequest(headers, method, url, body, nowMs = Date.now()) { + const header = name => { + const value = headers[name]; + + return Array.isArray(value) ? value[0] : value; + }; + + const agentHeader = header(AGENT_HEADER); + const key = header(PUBLIC_KEY_HEADER); + const timestamp = header(TIMESTAMP_HEADER); + const signature = header(SIGNATURE_HEADER); + if (!agentHeader || !key || !timestamp || !signature) + throw new ProxyRefusal('missing_signature'); + if (header(VERSION_HEADER) !== '2') + throw new ProxyRefusal('unsupported_signature_version'); + const agent = parseAgent(agentHeader); + const keyAgent = agentFromPublicKey(key); + if (!agent || !keyAgent) throw new ProxyRefusal('invalid_agent'); + if (agent !== keyAgent) throw new ProxyRefusal('agent_key_mismatch'); + if (!/^\d{1,16}$/.test(timestamp)) throw new ProxyRefusal('stale_timestamp'); + if (Math.abs(Number(timestamp) - nowMs) > MAX_SKEW_MS) + throw new ProxyRefusal('stale_timestamp'); + const message = requestMessage(method, url, timestamp, body); + if (!verifyBy(agent, message, signature)) + throw new ProxyRefusal('bad_signature'); + + return { + agent, + replayKey: `${REQUEST_DOMAIN}:${sha256Hex(Buffer.from(message))}`, + }; +} + +const CLAIMS = ['v', 'connection_id', 'platform', 'aud', 'app', 'cnf', 'exp']; + +/** `capability::parse`: structure and agent ids, not yet the signature. */ +export function parseCapability(token) { + if (typeof token !== 'string' || token.length > 4096) + throw new ProxyRefusal('invalid_capability'); + const dot = token.indexOf('.'); + if (dot === -1) throw new ProxyRefusal('invalid_capability'); + const payload = token.slice(0, dot); + const signature = token.slice(dot + 1); + if (!/^[A-Za-z0-9_-]+$/.test(payload)) + throw new ProxyRefusal('invalid_capability'); + const json = Buffer.from(payload, 'base64url'); + let claims; + + try { + claims = JSON.parse(json.toString('utf8')); + } catch { + throw new ProxyRefusal('invalid_capability'); + } + + const keys = claims && typeof claims === 'object' ? Object.keys(claims) : []; + if ( + keys.length !== CLAIMS.length || + !CLAIMS.every(k => keys.includes(k)) || + claims.v !== 2 || + typeof claims.connection_id !== 'string' || + typeof claims.platform !== 'string' || + typeof claims.aud !== 'string' || + !Number.isSafeInteger(claims.exp) || + claims.exp < 0 + ) + throw new ProxyRefusal('invalid_capability'); + const app = parseAgent(claims.app); + const cnf = parseAgent(claims.cnf); + if (!app || !cnf) throw new ProxyRefusal('invalid_capability'); + + return { claims, app, cnf, json, signature }; +} + +/** `Parsed::verify`: owner signature, audience, lifetime, in that order. */ +export function verifyCapability(parsed, owner, audience, nowSecs) { + const message = Buffer.concat([ + Buffer.from(`${CAPABILITY_DOMAIN}\n`), + parsed.json, + ]); + if (!verifyBy(owner, message, parsed.signature)) + throw new ProxyRefusal('invalid_capability'); + if (parsed.claims.aud !== audience) throw new ProxyRefusal('wrong_audience'); + if (parsed.claims.exp <= nowSecs) + throw new ProxyRefusal('capability_expired'); + if (parsed.claims.exp - nowSecs > MAX_CAPABILITY_SECS) + throw new ProxyRefusal('capability_too_long'); +} + +// ---- The client side, for tests ---- + +/** PKCS#8 DER prefix of a raw 32-byte Ed25519 seed. */ +const PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex'); + +/** An agent that signs like @tomic/lib does, from a 32-byte seed. */ +export function testSigner(seed) { + const privateKey = createPrivateKey({ + key: Buffer.concat([PKCS8_PREFIX, Buffer.from(seed)]), + format: 'der', + type: 'pkcs8', + }); + const publicKey = createPublicKey(privateKey).export({ format: 'jwk' }).x; + const agent = `atomic:agent:${publicKey}`; + const sign = bytes => b64url(edSign(null, Buffer.from(bytes), privateKey)); + + return { + agent, + publicKey, + sign, + /** v2 headers for one request; `timestamp` defaults to now. */ + headers(method, url, body = '', timestamp = Date.now()) { + return { + [AGENT_HEADER]: agent, + [PUBLIC_KEY_HEADER]: publicKey, + [TIMESTAMP_HEADER]: String(timestamp), + [SIGNATURE_HEADER]: sign(requestMessage(method, url, timestamp, body)), + [VERSION_HEADER]: '2', + }; + }, + }; +} + +/** What the page does: `payload.sig`, signed by `owner` (a `testSigner`). */ +export function mintCapability(owner, claims) { + const json = Buffer.from(JSON.stringify({ v: 2, ...claims })); + + return `${b64url(json)}.${owner.sign(Buffer.concat([Buffer.from(`${CAPABILITY_DOMAIN}\n`), json]))}`; +} diff --git a/integrations/localthought/mock-proxy.d.mts b/integrations/localthought/mock-proxy.d.mts index 2a24a3942..103aa916b 100644 --- a/integrations/localthought/mock-proxy.d.mts +++ b/integrations/localthought/mock-proxy.d.mts @@ -68,8 +68,33 @@ interface ClockifyFixture { control(command: { action: string; [key: string]: unknown }): unknown; } -export function mockProxy(options?: { frontendOrigin?: string }): Server & { +/** One connection as `GET /connections` and `/__mock/connections` list it. */ +export interface MockConnection { + connection_id: string; + platform: string; + /** Canonical `atomic:agent:`. */ + owner: string; + created_at: string; + last_used_at: string | null; + delegations: Array<{ + agent: string; + label: string | null; + created_at: string; + last_used_at: string | null; + }>; +} + +export function mockProxy(options?: { + frontendOrigin?: string; + platforms?: string | string[]; + /** The proxy's public origin (its BASE_URL); signatures cover it. */ + baseUrl?: string; + now?: () => number; +}): Server & { + fixtures: Record; github: GitHubTracker; calendar: CalendarFixture; clockify: ClockifyFixture; + /** The origin every signature and capability `aud` must name. */ + origin(): string; }; diff --git a/integrations/localthought/mock-proxy.mjs b/integrations/localthought/mock-proxy.mjs index bdf6684c1..7dae296e6 100644 --- a/integrations/localthought/mock-proxy.mjs +++ b/integrations/localthought/mock-proxy.mjs @@ -1,9 +1,33 @@ -/** Local-only integration-proxy fixture. Never deploy this service. */ +/** + * Local-only integration-proxy fixture. Never deploy this service. + * + * It speaks the integration proxy's 0.2 protocol (ontola/atomic-plugins#54, + * `integration-proxy/src/`): no proxy login; the page that redeems a handoff, + * signing with the user's Atomic key, owns the connection; the owner + * delegates it to app agents; a plugin frame calls `/proxy/{connection}/ + * {platform}/…` itself, with a capability the owner signed and a request + * signature by the frame's own key. Every signature is checked exactly as + * the real proxy checks it (`mock-proxy-auth.mjs`), so a host that signs + * wrongly fails here too. What it does not have: Postgres, OAuth with a real + * provider, sealed credentials, the 90-day idle sweep, the SaaS access policy. + * + * Providers are per-platform fixtures (fixtures/index.mjs). Test-side drivers + * (`/__fixture/…`, `/fixture//`) and introspection + * (`/__mock/…`) need no signature: this server only ever listens locally. + */ import { fixtures, selectPlatforms } from './fixtures/index.mjs'; +import { + ProxyRefusal, + parseAgent, + parseCapability, + verifyCapability, + verifyRequest, +} from './mock-proxy-auth.mjs'; import { readFileSync } from 'node:fs'; import { createServer } from 'node:http'; import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'; import { pathToFileURL } from 'node:url'; + const equal = (a, b) => typeof a === 'string' && typeof b === 'string' && @@ -11,14 +35,40 @@ const equal = (a, b) => timingSafeEqual(Buffer.from(a), Buffer.from(b)); const pkceChallenge = verifier => createHash('sha256').update(verifier).digest('base64url'); +/** 32 random bytes, base64url: the length of the proxy's ids and codes (43). */ +const random = () => randomBytes(32).toString('base64url'); +const escape = text => + String(text).replace( + /[&<>"']/g, + c => + ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[ + c + ], + ); +const HANDOFF_MS = 5 * 60 * 1000; +const REPLAY_MS = 10 * 60 * 1000; +const MAX_LABEL = 200; + +/** Whether a fixture's catalog document declares an API-key scheme. */ +const requiresApiKey = fixture => + Object.values(fixture.document?.components?.securitySchemes ?? {}).some( + scheme => scheme?.type === 'apiKey', + ); /** * `platforms` restricts which fixtures load (see fixtures/index.mjs); it * defaults to MOCK_PROXY_PLATFORMS, and to every fixture when that is unset. + * + * `baseUrl` is the proxy's public origin, as the real proxy's BASE_URL: the + * URL every request signature covers and every capability's `aud`. It + * defaults to MOCK_PROXY_BASE_URL, then to `http://127.0.0.1:` once + * listening. Clients must use exactly this origin. */ export function mockProxy({ frontendOrigin = process.env.MOCK_FRONTEND_ORIGIN ?? 'http://localhost:6747', platforms = process.env.MOCK_PROXY_PLATFORMS, + baseUrl = process.env.MOCK_PROXY_BASE_URL, + now = Date.now, } = {}) { const selected = selectPlatforms( Array.isArray(platforms) ? platforms.join(',') : platforms, @@ -30,31 +80,165 @@ export function mockProxy({ const instances = Object.fromEntries( selected.platforms.map(id => [id, fixtures[id].create()]), ); - const codes = new Map(); + /** csrf -> the validated /connect request, until the consent form posts. */ + const consents = new Map(); + /** handoff code -> { platform, codeChallenge, expires }. */ const handoffs = new Map(); + /** connection id -> row; delegations keyed by canonical agent. */ + const connections = new Map(); + /** `${owner} ${agent}` -> runtime row. */ + const runtimes = new Map(); + /** single-use record of signed requests: replay key -> expiry. */ + const used = new Map(); + + const origin = () => + (baseUrl ?? `http://127.0.0.1:${server.address().port}`).replace(/\/$/, ''); + const stamp = () => new Date(now()).toISOString(); + + /** `signature::authenticate`: verify, then spend. */ + const authenticate = (req, body) => { + const verified = verifyRequest( + req.headers, + req.method, + `${origin()}${req.url}`, + body, + now(), + ); + for (const [key, expires] of used) if (expires < now()) used.delete(key); + if (used.has(verified.replayKey)) throw new ProxyRefusal('replayed'); + used.set(verified.replayKey, now() + REPLAY_MS); + + return verified.agent; + }; + + const owned = (signer, id) => { + const row = connections.get(id); + if (!row) throw new ProxyRefusal('unknown_connection'); + if (row.owner !== signer) throw new ProxyRefusal('not_owner'); + + return row; + }; + + const agentArg = id => { + const agent = parseAgent(id); + if (!agent) + throw new ProxyRefusal('bad_request', 'agent must be an atomic:agent id'); + + return agent; + }; + + const labelArg = label => { + if (label === undefined || label === null) return null; + if (typeof label !== 'string' || [...label].length > MAX_LABEL) + throw new ProxyRefusal( + 'bad_request', + 'label is longer than 200 characters', + ); + + return label; + }; + + const strictBody = (body, allowed, required, usage) => { + let value; + + try { + value = JSON.parse(body.toString('utf8')); + } catch { + throw new ProxyRefusal('bad_request', usage); + } + + if ( + !value || + typeof value !== 'object' || + Array.isArray(value) || + Object.keys(value).some(k => !allowed.includes(k)) || + required.some(k => typeof value[k] !== 'string') + ) + throw new ProxyRefusal('bad_request', usage); + + return value; + }; + + /** The standing of a signer for a connection (`Security::standing`). */ + const standing = (row, signer) => { + if (row.owner === signer) return { kind: 'owner' }; + if (row.delegations.has(signer)) return { kind: 'delegate', app: signer }; + const runtime = runtimes.get(`${row.owner} ${signer}`); + if (runtime && row.delegations.has(runtime.app)) + return { kind: 'runtime', app: runtime.app, runtime }; + + return undefined; + }; + + /** `proxy::authenticate`. Returns the app that used it, if any. */ + const authenticateProxied = (req, body, row, platform) => { + const authorization = req.headers.authorization; + let caller; + + if (authorization !== undefined) { + if (!authorization.startsWith('Capability ')) + throw new ProxyRefusal('unsupported_authorization'); + const parsed = parseCapability(authorization.slice('Capability '.length)); + verifyCapability(parsed, row.owner, origin(), Math.floor(now() / 1000)); + if ( + parsed.claims.connection_id !== row.connection_id || + parsed.claims.platform !== platform || + row.platform !== platform + ) + throw new ProxyRefusal('capability_scope'); + if (!row.delegations.has(parsed.app)) + throw new ProxyRefusal('not_delegated'); + if (authenticate(req, body) !== parsed.cnf) + throw new ProxyRefusal('capability_key_mismatch'); + caller = { kind: 'frame', app: parsed.app }; + } else { + caller = standing(row, authenticate(req, body)); + if (!caller) throw new ProxyRefusal('not_delegated'); + } - const issueCode = platform => { - const code = randomBytes(32).toString('base64url'); - codes.set(code, platform); + if (row.platform !== platform) throw new ProxyRefusal('platform_mismatch'); + row.last_used_at = stamp(); + if (caller.app) row.delegations.get(caller.app).last_used_at = stamp(); + if (caller.runtime) caller.runtime.last_used_at = stamp(); - return code; + return caller; }; - const server = createServer(async (req, res) => { + const listFor = owner => ({ + owner, + connections: [...connections.values()] + .filter(row => row.owner === owner) + .map(publicRow), + runtimes: [...runtimes.values()] + .filter(r => r.owner === owner) + .map(({ agent, app, label, created_at, last_used_at }) => ({ + agent, + app, + label, + created_at, + last_used_at, + })), + }); + + const handle = async (req, res) => { res.setHeader('Access-Control-Allow-Origin', '*'); res.setHeader( 'Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS', ); - // As integration-proxy's browser_cors(): If-Match in, ETag and - // Retry-After out, so a conditional write works the same here. + // As integration-proxy's browser_cors(): the signature headers and + // Authorization (for a capability) in; If-Match in, ETag and Retry-After + // out, so a conditional write works the same here. Last-Page is exposed + // for the Clockify fixture; the real proxy does not expose it (and the + // host's frame client forwards only link, retry-after, etag and + // content-type anyway). res.setHeader( 'Access-Control-Allow-Headers', - 'Authorization, Content-Type, If-Match', + 'Authorization, Content-Type, If-Match, x-atomic-agent, x-atomic-public-key, x-atomic-timestamp, x-atomic-signature, x-atomic-signature-version', ); res.setHeader( 'Access-Control-Expose-Headers', - 'X-Connection-Code, Link, Retry-After, ETag, Last-Page', + 'Content-Type, Link, Retry-After, ETag, X-Total-Count, X-Next-Page, Last-Page', ); if (req.method === 'OPTIONS') { @@ -70,6 +254,30 @@ export function mockProxy({ res.end(JSON.stringify(value)); }; + const refuse = error => { + if (!(error instanceof ProxyRefusal)) throw error; + + return json( + error.status, + { error: error.code, message: error.message }, + { 'Cache-Control': 'no-store' }, + ); + }; + + /** The raw body, at most `limit` bytes; `undefined` when larger. */ + const readBody = async limit => { + const chunks = []; + let size = 0; + + for await (const chunk of req) { + size += chunk.length; + if (size > limit) return undefined; + chunks.push(chunk); + } + + return Buffer.concat(chunks); + }; + if (url.pathname === '/catalog') return json(200, selected.platforms); const catalogFile = url.pathname.match( /^\/catalog\/([^/]+)\.(selection\.json|yaml)$/, @@ -88,16 +296,20 @@ export function mockProxy({ } } + // GET /connect: the consent page. No login and no user_id: whoever + // redeems the handoff, signing with their key, becomes the owner. if (url.pathname === '/connect') { + if (req.method !== 'GET') return json(405, {}); const p = url.searchParams; const platform = p.get('platform'); - const verifierChallenge = p.get('code_challenge'); + const challenge = p.get('code_challenge') ?? ''; + // The retired flow's parameters: a host still sending them is stale. + const legacy = ['user_id', 'credentials', 'tenant_id', 'user_id_sig']; if ( !Object.hasOwn(instances, platform) || - !verifierChallenge || + !/^[A-Za-z0-9_-]{43}$/.test(challenge) || p.get('code_challenge_method') !== 'S256' || - p.get('credentials') !== 'connection' || - !p.get('user_id') + legacy.some(name => p.has(name)) ) return json(400, { error: 'Invalid connection request' }); let redirect; @@ -105,70 +317,263 @@ export function mockProxy({ try { redirect = new URL(p.get('redirect_uri')); } catch { - return json(400, { error: 'Invalid callback' }); + return json(400, { error: 'Invalid return address' }); } + // Stricter than the real proxy (any https, loopback http or atomic: + // address): the e2e host must return to its own /app/integrations. if ( redirect.origin !== frontendOrigin || !['/app/integrations', '/app/devonian-demo'].includes( redirect.pathname, ) || + redirect.hash || + redirect.searchParams.has('connection_code') || + redirect.searchParams.has('error') || !redirect.searchParams.get('integration_state') || redirect.searchParams.get('platform') !== platform ) - return json(400, { error: 'Invalid callback' }); + return json(400, { error: 'Invalid return address' }); + + const csrf = random(); + consents.set(csrf, { + platform, + codeChallenge: challenge, + redirect: redirect.href, + expires: now() + HANDOFF_MS, + }); + const title = escape(fixtures[platform].title); + const apiKey = requiresApiKey(fixtures[platform]); + res.writeHead(200, { + 'Content-Type': 'text/html', + 'Cache-Control': 'no-store', + }); - if (req.method === 'GET') { - res.writeHead(200, { 'Content-Type': 'text/html' }); + // Mirrors templates.rs: an API-key platform asks for the key here; an + // OAuth one would go to the provider next (the mock skips that). + return res.end( + `

Mock integration proxy

Connect ${title}

Destination: ${escape(redirect.origin)}

The destination finishes connecting by signing with your Atomic key; it becomes the connection's owner.

${ + apiKey + ? `` + : `` + }
`, + ); + } - return res.end( - `

Mock integration proxy

Signed in as mock-user.

Use the selected ${fixtures[platform].title} account to sync with your Atomic Data Hub.

`, - ); + // POST /connect/authorize: the consent form. The real proxy goes to the + // provider's OAuth here (or seals the pasted key); the mock stands in for + // the provider saying yes, and returns a single-use handoff code. + if (url.pathname === '/connect/authorize') { + if (req.method !== 'POST') return json(405, {}); + const body = await readBody(16 * 1024); + if (!body) return json(413, {}); + const form = new URLSearchParams(body.toString('utf8')); + const consent = consents.get(form.get('csrf') ?? ''); + consents.delete(form.get('csrf') ?? ''); + if (!consent || consent.expires < now()) + return json(400, { error: 'Invalid or expired consent' }); + const redirect = new URL(consent.redirect); + + if (form.get('cancel')) { + redirect.searchParams.set('error', 'access_denied'); + } else { + if ( + requiresApiKey(fixtures[consent.platform]) && + !form.get('api_key')?.trim() + ) + return json(400, { error: 'An API key is required' }); + const code = random(); + handoffs.set(code, { + platform: consent.platform, + codeChallenge: consent.codeChallenge, + expires: now() + HANDOFF_MS, + }); + redirect.searchParams.set('connection_code', code); } - if (req.method !== 'POST') return json(405, {}); - const handoff = randomBytes(32).toString('base64url'); - handoffs.set(handoff, { - platform, - userId: p.get('user_id'), - codeChallenge: verifierChallenge, - }); - redirect.searchParams.set('connection_code', handoff); res.writeHead(303, { Location: redirect.href }); return res.end(); } + // POST /connect/redeem, signed: the signer becomes the owner. if (url.pathname === '/connect/redeem') { if (req.method !== 'POST') return json(405, {}); - let body; + const body = await readBody(16 * 1024); + if (!body) return json(413, {}); try { - let text = ''; + const owner = authenticate(req, body); + const request = strictBody( + body, + ['code', 'code_verifier'], + ['code', 'code_verifier'], + 'body must be {"code", "code_verifier"}', + ); + const handoff = handoffs.get(request.code); + if ( + !handoff || + handoff.expires < now() || + request.code_verifier.length < 43 || + !equal(pkceChallenge(request.code_verifier), handoff.codeChallenge) + ) + throw new ProxyRefusal('invalid_handoff'); + handoffs.delete(request.code); + const connectionId = random(); + connections.set(connectionId, { + connection_id: connectionId, + platform: handoff.platform, + owner, + created_at: stamp(), + last_used_at: null, + delegations: new Map(), + }); + + return json( + 200, + { connection_id: connectionId, platform: handoff.platform, owner }, + { 'Cache-Control': 'no-store' }, + ); + } catch (error) { + return refuse(error); + } + } - for await (const chunk of req) { - text += chunk; - if (text.length > 16 * 1024) return json(413, {}); + // Management, signed by the owner. + const management = + url.pathname === '/connections' || + url.pathname === '/runtimes' || + /^\/(connections|runtimes)\/[^/]+(\/agents(\/[^/]+)?)?$/.test( + url.pathname, + ); + + if (management) { + const body = await readBody(16 * 1024); + if (!body) return json(413, {}); + const segments = url.pathname.split('/').slice(1).map(decodeURIComponent); + + try { + const signer = authenticate(req, body); + const [collection, id, sub, agent] = segments; + const noStore = { 'Cache-Control': 'no-store' }; + + if (collection === 'connections' && !id && req.method === 'GET') + return json(200, listFor(signer), noStore); + + if (collection === 'connections' && id && !sub) { + if (req.method !== 'DELETE') return json(405, {}); + owned(signer, id); + connections.delete(id); + res.writeHead(204, noStore); + + return res.end(); } - body = JSON.parse(text); - } catch { - return json(400, { error: 'Invalid redemption body' }); - } + if (collection === 'connections' && sub === 'agents') { + const row = owned(signer, id); + + if (!agent && req.method === 'POST') { + const request = strictBody( + body, + ['agent', 'label'], + ['agent'], + 'body must be {"agent", "label"?}', + ); + const delegate = agentArg(request.agent); + const label = labelArg(request.label); + const previous = row.delegations.get(delegate); + row.delegations.set(delegate, { + agent: delegate, + label, + created_at: previous?.created_at ?? stamp(), + last_used_at: previous?.last_used_at ?? null, + }); + + return json( + 200, + { connection_id: id, agent: delegate, label }, + noStore, + ); + } - const handoff = handoffs.get(body?.code); - if ( - !handoff || - typeof body?.code_verifier !== 'string' || - !equal(pkceChallenge(body.code_verifier), handoff.codeChallenge) - ) - return json(400, { error: 'Invalid or consumed connection code' }); - handoffs.delete(body.code); + if (agent && req.method === 'DELETE') { + row.delegations.delete(agentArg(agent)); + res.writeHead(204, noStore); + + return res.end(); + } + + return json(405, {}); + } + + if (collection === 'runtimes' && !id && req.method === 'POST') { + const request = strictBody( + body, + ['app', 'agent', 'label'], + ['app', 'agent'], + 'body must be {"app", "agent", "label"?}', + ); + const app = agentArg(request.app); + const runtime = agentArg(request.agent); + if (runtime === app || runtime === signer) + throw new ProxyRefusal( + 'bad_request', + 'a runtime must be its own agent, not the app or the owner', + ); + const label = labelArg(request.label); + runtimes.set(`${signer} ${runtime}`, { + owner: signer, + agent: runtime, + app, + label, + created_at: stamp(), + last_used_at: null, + }); + + return json(200, { app, agent: runtime, label }, noStore); + } + + if (collection === 'runtimes' && id && req.method === 'DELETE') { + runtimes.delete(`${signer} ${agentArg(id)}`); + res.writeHead(204, noStore); + return res.end(); + } + + return json(405, {}); + } catch (error) { + return refuse(error); + } + } + + // Test-side introspection, as a spec in another process needs it: + // every connection with its owner, delegations and runtimes; never a + // credential (the mock holds none). Local-only, like the drivers. + if (url.pathname === '/__mock/connections' && req.method === 'GET') return json(200, { - connection_code: issueCode(handoff.platform), - platform: handoff.platform, + connections: [...connections.values()].map(publicRow), + runtimes: [...runtimes.values()], }); + + // Test-side changes a person would make elsewhere (another device, the + // proxy's own management UI): drop one delegation, or a whole + // connection (as the 90-day idle sweep would). + if (url.pathname === '/__mock/revoke' && req.method === 'POST') { + const body = await readBody(16 * 1024); + let command; + + try { + command = JSON.parse(body?.toString('utf8') || '{}'); + } catch { + return json(400, { error: 'Invalid command' }); + } + + const row = connections.get(command.connection_id); + if (!row) return json(404, {}); + if (command.agent === undefined) connections.delete(row.connection_id); + else row.delegations.delete(parseAgent(command.agent)); + + return json(200, {}); } // Test-side driver for a fixture that offers `control(command)`, so an @@ -185,13 +590,8 @@ export function mockProxy({ let command; try { - let text = ''; - - for await (const chunk of req) { - text += chunk; - if (text.length > 64 * 1024) return json(413, {}); - } - + const text = (await readBody(64 * 1024))?.toString('utf8'); + if (text === undefined) return json(413, {}); command = text ? JSON.parse(text) : {}; } catch { return json(400, { error: 'Invalid fixture command' }); @@ -231,34 +631,52 @@ export function mockProxy({ } } - if (url.pathname.startsWith('/proxy/')) { - const code = req.headers.authorization?.replace(/^Bearer /, ''); - const platform = codes.get(code); - if (!platform) - return json(401, { error: 'Invalid or consumed connection code' }); - codes.delete(code); - const headers = { 'X-Connection-Code': issueCode(platform) }; - if (!url.pathname.startsWith(`/proxy/${platform}/`)) - return json(403, {}, headers); + // ANY /proxy/{connection_id}/{platform}/{*path} + // Matched on the path as sent: URL parsing would resolve a `%2e%2e` + // segment before the traversal check could see it. + const proxied = req.url + .split('?')[0] + .match(/^\/proxy\/([^/]+)\/([^/]+)\/(.*)$/); + + if (proxied) { + const [, rawId, platform, rest] = proxied; + if ( + rest + .split('/') + .some(s => ['.', '..'].includes(decodeURIComponent(s).trim())) + ) + return refuse( + new ProxyRefusal( + 'bad_request', + 'path must not contain traversal segments', + ), + ); + const body = await readBody(1024 * 1024); + if (!body) return json(413, {}); + const row = connections.get(decodeURIComponent(rawId)); + + try { + if (!row) throw new ProxyRefusal('unknown_connection'); + authenticateProxied(req, body, row, platform); + } catch (error) { + return refuse(error); + } + if (!Object.hasOwn(instances, platform)) return json(404, {}); const fixture = fixtures[platform]; let input = {}; - if (fixture.jsonBody) { + if (fixture.jsonBody && body.length) { try { - let body = ''; - - for await (const chunk of req) { - body += chunk; - if (body.length > 1024 * 1024) return json(413, {}, headers); - } - - if (body) input = JSON.parse(body); + input = JSON.parse(body.toString('utf8')); } catch { - return json(400, { error: 'Invalid request body' }, headers); + return json(400, { error: 'Invalid request body' }); } } + // Fixtures see the provider path under `/proxy//`, as they + // did before connections moved into the path. + const upstream = new URL(`/proxy/${platform}/${rest}${url.search}`, url); // Only the one request header the real proxy forwards upstream besides // Content-Type (proxy.rs upstream_request); never Authorization. const forwarded = req.headers['if-match'] @@ -268,19 +686,26 @@ export function mockProxy({ // response; see the Clockify fixture's `applyThenDrop`). const result = await instances[platform].request( req.method, - url, + upstream, input, forwarded, ); - return json(result.status, result.body, { - ...headers, - ...result.headers, - }); + return json(result.status, result.body, result.headers ?? {}); } json(404, {}); + }; + + const server = createServer((req, res) => { + handle(req, res).catch(error => { + // A malformed request (e.g. a bad %-escape) must not take the mock down. + console.error('mock-proxy:', error); + if (!res.headersSent) res.writeHead(500); + res.end(); + }); }); + // Test-side drivers, e.g. server.fixtures['github-issues'].createIssue(). // The short aliases predate the registry; callers outside this repo // (atomic-server's browser/e2e specs) may still use them. @@ -288,22 +713,36 @@ export function mockProxy({ server.github = instances['github-issues']; server.calendar = instances['google-calendar']; server.clockify = instances.clockify; + /** In-process view of the proxy's own state, for tests. */ + server.proxyState = { connections, runtimes, handoffs }; + server.origin = origin; return server; } +function publicRow(row) { + return { + connection_id: row.connection_id, + platform: row.platform, + owner: row.owner, + created_at: row.created_at, + last_used_at: row.last_used_at, + delegations: [...row.delegations.values()], + }; +} + if ( process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href ) { - mockProxy().listen( - Number(process.env.MOCK_PROXY_PORT ?? 19090), - process.env.MOCK_PROXY_HOST ?? '127.0.0.1', - function () { - const { address, port } = this.address(); - console.log( - `Mock integration proxy listening on http://${address}:${port}`, - ); - }, - ); + const host = process.env.MOCK_PROXY_HOST ?? '127.0.0.1'; + const port = Number(process.env.MOCK_PROXY_PORT ?? 19090); + mockProxy({ + baseUrl: process.env.MOCK_PROXY_BASE_URL ?? `http://${host}:${port}`, + }).listen(port, host, function () { + const { address, port: bound } = this.address(); + console.log( + `Mock integration proxy listening on http://${address}:${bound}`, + ); + }); } diff --git a/integrations/localthought/mock-proxy.test.mjs b/integrations/localthought/mock-proxy.test.mjs index 07a660735..458112ea0 100644 --- a/integrations/localthought/mock-proxy.test.mjs +++ b/integrations/localthought/mock-proxy.test.mjs @@ -1,15 +1,301 @@ +/** + * The mock integration proxy speaks the real proxy's 0.2 protocol + * (ontola/atomic-plugins#54). Run without an atomic-server checkout: + * + * node --test integrations/localthought/mock-proxy.test.mjs + */ import { test } from 'node:test'; import assert from 'node:assert/strict'; import { createHash } from 'node:crypto'; +import { readFileSync } from 'node:fs'; +import { request } from 'node:http'; import { mockProxy } from './mock-proxy.mjs'; +import { + MAX_CAPABILITY_SECS, + ProxyRefusal, + agentFromPublicKey, + mintCapability, + parseAgent, + parseCapability, + testSigner, + verifyCapability, + verifyRequest, +} from './mock-proxy-auth.mjs'; const verifier = 'a'.repeat(64); const challenge = createHash('sha256').update(verifier).digest('base64url'); +const FRONTEND = 'http://localhost:6747'; +const owner = testSigner(Buffer.alloc(32, 1)); +const app = testSigner(Buffer.alloc(32, 2)); +const frame = testSigner(Buffer.alloc(32, 3)); +const stranger = testSigner(Buffer.alloc(32, 4)); +const node = testSigner(Buffer.alloc(32, 5)); -test('catalog, selected-platform PKCE consent, redemption and single-use rotation', async () => { - const server = mockProxy({ platforms: '' }); +/** The shared golden vectors, copied from atomic-server into the proxy. */ +const vectors = JSON.parse( + readFileSync( + new URL( + '../../integration-proxy/tests/fixtures/atomic-request-v2-vectors.json', + import.meta.url, + ), + ), +).vectors; + +/** + * atomic-server's capability vector (`browser/data-browser/src/helpers/ + * proxyConnections.test.ts`, "capability vector"), signed by the vectors' + * user key; see plans/issue-54-atomic-server.md. + */ +const CAPABILITY_VECTOR = + 'eyJ2IjoyLCJjb25uZWN0aW9uX2lkIjoiY18xMjMiLCJwbGF0Zm9ybSI6Imdvb2dsZS1jYWxlbmRhciIsImF1ZCI6Imh0dHBzOi8vcHJveHkuZXhhbXBsZSIsImFwcCI6ImF0b21pYzphZ2VudDpBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFFIiwiY25mIjoiYXRvbWljOmFnZW50OkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkUiLCJleHAiOjE3OTAwMDA2MDB9.mKOEe3SnRDDRYFZ94kAqkXl_RnRy-pS-B5KdEzpdQVDPNE3PEHZq1e7aT9dL0GKhv00uZ2WiWmftEvto09xRDw'; + +async function start(options = {}) { + const server = mockProxy({ frontendOrigin: FRONTEND, ...options }); await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); - const base = `http://127.0.0.1:${server.address().port}`; + + return { + server, + base: `http://127.0.0.1:${server.address().port}`, + async close() { + server.closeAllConnections(); + await new Promise(resolve => server.close(resolve)); + }, + }; +} + +const refusal = code => error => + error instanceof ProxyRefusal && error.code === code; + +/** A v2-signed fetch, signed over exactly the URL and body sent. */ +function signed(signer, method, url, { body, headers = {}, at } = {}) { + return fetch(url, { + method, + headers: { + ...headers, + ...(body === undefined ? {} : { 'Content-Type': 'application/json' }), + ...signer.headers(method, new URL(url).href, body ?? '', at), + }, + ...(body === undefined ? {} : { body }), + }); +} + +async function errorOf(response) { + return [response.status, (await response.json()).error]; +} + +function connectUrl(base, platform, extra = {}) { + const url = new URL(`${base}/connect`); + url.search = new URLSearchParams({ + redirect_uri: `${FRONTEND}/app/integrations?integration_state=abc&platform=${platform}`, + platform, + code_challenge: challenge, + code_challenge_method: 'S256', + ...extra, + }); + + return url; +} + +/** The consent page and its form, as a browser would post it. */ +async function consent(base, platform, fields = {}) { + const page = await fetch(connectUrl(base, platform)); + assert.equal(page.status, 200, await page.clone().text()); + const html = await page.text(); + const csrf = /name="csrf" value="([^"]+)"/.exec(html)[1]; + + return { + html, + submit: () => + fetch(`${base}/connect/authorize`, { + method: 'POST', + redirect: 'manual', + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + body: new URLSearchParams({ csrf, ...fields }), + }), + }; +} + +/** + * The whole connect flow the data browser page runs: consent, redeem signed + * by the owner, delegation to the app. Returns the connection id. + */ +async function connect(base, platform, fields = {}) { + const { submit } = await consent(base, platform, fields); + const back = new URL((await submit()).headers.get('location')); + const code = back.searchParams.get('connection_code'); + const redeemed = await signed(owner, 'POST', `${base}/connect/redeem`, { + body: JSON.stringify({ code, code_verifier: verifier }), + }); + assert.equal(redeemed.status, 200); + const { connection_id: id } = await redeemed.json(); + const delegated = await signed( + owner, + 'POST', + `${base}/connections/${id}/agents`, + { body: JSON.stringify({ agent: app.agent, label: 'Test app' }) }, + ); + assert.equal(delegated.status, 200); + + return id; +} + +/** + * What a plugin frame does (atomic-server's view-client.js): a capability + * from the page, then each request signed with the frame's own key. + */ +function frameClient(base, id, platform, claims = {}) { + const capability = mintCapability(owner, { + connection_id: id, + platform, + aud: base, + app: app.agent, + cnf: frame.agent, + exp: Math.floor(Date.now() / 1000) + 600, + ...claims, + }); + + return (method, path, { body, ifMatch, signer = frame, signal } = {}) => + fetch(`${base}/proxy/${id}/${platform}${path}`, { + method, + signal, + headers: { + Authorization: `Capability ${capability}`, + ...(body === undefined ? {} : { 'Content-Type': 'application/json' }), + ...(ifMatch ? { 'If-Match': ifMatch } : {}), + ...signer.headers( + method, + new URL(`${base}/proxy/${id}/${platform}${path}`).href, + body ?? '', + ), + }, + ...(body === undefined ? {} : { body }), + }); +} + +test('the shared v2 request vectors verify here, and nothing else does', () => { + assert.ok(vectors.length >= 4); + + for (const v of vectors) { + const headers = { + 'x-atomic-agent': v.agent, + 'x-atomic-public-key': v.public_key, + 'x-atomic-timestamp': String(v.timestamp), + 'x-atomic-signature': v.signature, + 'x-atomic-signature-version': '2', + }; + assert.equal( + verifyRequest(headers, v.method, v.url, v.body, v.timestamp).agent, + v.agent, + v.name, + ); + // The same signer re-derives the same (deterministic) signature. + assert.equal( + testSigner(Buffer.from(v.private_key, 'base64')).headers( + v.method, + v.url, + v.body, + v.timestamp, + )['x-atomic-signature'], + v.signature.replace(/=+$/, ''), + v.name, + ); + + for (const [method, url, body] of [ + [v.method === 'GET' ? 'POST' : 'GET', v.url, v.body], + [v.method, `${v.url}x`, v.body], + [v.method, v.url, `${v.body} `], + ]) + assert.throws( + () => verifyRequest(headers, method, url, body, v.timestamp), + refusal('bad_signature'), + v.name, + ); + assert.throws( + () => + verifyRequest( + { ...headers, 'x-atomic-signature-version': undefined }, + v.method, + v.url, + v.body, + v.timestamp, + ), + refusal('unsupported_signature_version'), + ); + assert.throws( + () => + verifyRequest(headers, v.method, v.url, v.body, v.timestamp + 300_001), + refusal('stale_timestamp'), + ); + } +}); + +test("atomic-server's capability vector verifies here", () => { + const parsed = parseCapability(CAPABILITY_VECTOR); + const user = parseAgent( + 'atomic:agent:O2onvM62pC1io6jQKm8Nc2UyFXcd4kOmOsBIoYtZ2ik', + ); + assert.deepEqual(parsed.claims, { + v: 2, + connection_id: 'c_123', + platform: 'google-calendar', + aud: 'https://proxy.example', + app: `atomic:agent:${'A'.repeat(42)}E`, + cnf: `atomic:agent:${'B'.repeat(42)}E`, + exp: 1790000600, + }); + verifyCapability(parsed, user, 'https://proxy.example', 1790000000); + assert.throws( + () => + verifyCapability( + parsed, + owner.agent, + 'https://proxy.example', + 1790000000, + ), + refusal('invalid_capability'), + ); + assert.throws( + () => verifyCapability(parsed, user, 'https://other.example', 1790000000), + refusal('wrong_audience'), + ); + assert.throws( + () => verifyCapability(parsed, user, 'https://proxy.example', 1790000600), + refusal('capability_expired'), + ); + assert.throws( + () => + verifyCapability( + parsed, + user, + 'https://proxy.example', + 1790000600 - MAX_CAPABILITY_SECS - 1, + ), + refusal('capability_too_long'), + ); +}); + +test('agent ids: both prefixes and alphabets, one canonical form', () => { + const key = owner.publicKey; + const standard = Buffer.from(key, 'base64url').toString('base64'); + for (const id of [ + `atomic:agent:${key}`, + `did:ad:agent:${key}`, + `atomic:agent:${standard}`, + `did:ad:agent:${standard.replace(/=+$/, '')}`, + ]) + assert.equal(parseAgent(id), owner.agent, id); + for (const id of [ + 'https://example.com/agents/x', + `atomic:agent:${key.slice(1)}`, + `atomic:agent:${key}!`, + 'atomic:agent:', + ]) + assert.equal(parseAgent(id), undefined, id); + assert.equal(agentFromPublicKey(key), owner.agent); +}); + +test('connect: consent without login, signed redeem makes the owner, delegation, frame capability', async () => { + const { base, server, close } = await start({ platforms: '' }); try { assert.deepEqual(await (await fetch(`${base}/catalog`)).json(), [ @@ -19,79 +305,429 @@ test('catalog, selected-platform PKCE consent, redemption and single-use rotatio 'notion', 'pets', ]); - const callback = - 'http://localhost:6747/app/integrations?integration_state=abc&platform=pets'; - const url = new URL(`${base}/connect`); - url.search = new URLSearchParams({ - redirect_uri: callback, - platform: 'pets', - user_id: 'synthetic-agent', - code_challenge: challenge, - code_challenge_method: 'S256', - credentials: 'connection', - }); - const login = await fetch(url); - assert.equal(login.status, 200); - const loginHtml = await login.text(); - assert.match( - loginHtml, - /Use LocalThought to sync Pets with your Atomic Data Hub/, - ); - assert.doesNotMatch(loginHtml, /tenant secret/i); - assert.doesNotMatch(loginHtml, /GitHub|Google Calendar/); - const badPlatform = new URL(url); - badPlatform.searchParams.set('platform', 'github-issues'); - assert.equal((await fetch(badPlatform)).status, 400); + // The retired flow's parameters, a foreign return address, an unknown + // platform and a weak challenge are all refused. + for (const url of [ + connectUrl(base, 'pets', { user_id: 'synthetic-agent' }), + connectUrl(base, 'pets', { credentials: 'connection' }), + connectUrl(base, 'pets', { code_challenge: 'short' }), + connectUrl(base, 'nope'), + ]) + assert.equal((await fetch(url)).status, 400, url.href); + const foreign = connectUrl(base, 'pets'); + foreign.searchParams.set( + 'redirect_uri', + 'http://evil.example/app/integrations?integration_state=abc&platform=pets', + ); + assert.equal((await fetch(foreign)).status, 400); - const consent = await fetch(url, { method: 'POST', redirect: 'manual' }); - assert.equal(consent.status, 303); - const location = new URL(consent.headers.get('location')); - const handoff = location.searchParams.get('connection_code'); - assert.equal(location.searchParams.get('platform'), 'pets'); - assert.ok(handoff); + const { html, submit } = await consent(base, 'pets'); + assert.match(html, /Use LocalThought to sync Pets with this destination/); + assert.doesNotMatch(html, /API key|GitHub|Google Calendar/); + const back = new URL((await submit()).headers.get('location')); + assert.equal(back.origin, FRONTEND); + assert.equal(back.searchParams.get('platform'), 'pets'); + const code = back.searchParams.get('connection_code'); + assert.equal(code.length, 43); + // The consent form is single use. + assert.equal((await submit()).status, 400); - const redeem = codeVerifier => - fetch(`${base}/connect/redeem`, { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ code: handoff, code_verifier: codeVerifier }), + const redeem = (signer, codeVerifier = verifier, extra = {}) => + signed(signer, 'POST', `${base}/connect/redeem`, { + body: JSON.stringify({ code, code_verifier: codeVerifier, ...extra }), }); - assert.equal((await redeem('wrong-verifier')).status, 400); - const redeemed = await redeem(verifier); + const unsigned = await fetch(`${base}/connect/redeem`, { + method: 'POST', + body: JSON.stringify({ code, code_verifier: verifier }), + }); + assert.deepEqual(await errorOf(unsigned), [401, 'missing_signature']); + assert.deepEqual(await errorOf(await redeem(owner, 'b'.repeat(64))), [ + 400, + 'invalid_handoff', + ]); + assert.deepEqual(await errorOf(await redeem(owner, verifier, { x: 1 })), [ + 400, + 'bad_request', + ]); + const redeemed = await redeem(owner); assert.equal(redeemed.status, 200); const result = await redeemed.json(); + assert.deepEqual(Object.keys(result).sort(), [ + 'connection_id', + 'owner', + 'platform', + ]); assert.equal(result.platform, 'pets'); - assert.equal(typeof result.connection_code, 'string'); - assert.ok(result.connection_code); - assert.equal((await redeem(verifier)).status, 400); + assert.equal(result.owner, owner.agent); + const id = result.connection_id; + assert.deepEqual(await errorOf(await redeem(owner)), [ + 400, + 'invalid_handoff', + ]); - const read = (token, query = '') => - fetch(`${base}/proxy/pets/pets${query}`, { - headers: { Authorization: `Bearer ${token}` }, + // Listed for the owner only. + const list = async signer => + (await signed(signer, 'GET', `${base}/connections`)).json(); + const mine = await list(owner); + assert.equal(mine.owner, owner.agent); + assert.deepEqual( + mine.connections.map(c => [c.connection_id, c.platform, c.delegations]), + [[id, 'pets', []]], + ); + assert.deepEqual((await list(stranger)).connections, []); + + // Not delegated yet: a frame capability is refused. + const call = frameClient(base, id, 'pets'); + assert.deepEqual(await errorOf(await call('GET', '/pets')), [ + 403, + 'not_delegated', + ]); + + // Only the owner delegates; a did:ad spelling is stored canonically. + const delegate = (signer, body) => + signed(signer, 'POST', `${base}/connections/${id}/agents`, { + body: JSON.stringify(body), }); - const first = await read(result.connection_code); + assert.deepEqual( + await errorOf(await delegate(stranger, { agent: app.agent })), + [403, 'not_owner'], + ); + assert.deepEqual( + await errorOf(await delegate(owner, { agent: 'https://x.example/a' })), + [400, 'bad_request'], + ); + const delegated = await delegate(owner, { + agent: app.agent.replace('atomic:agent:', 'did:ad:agent:'), + label: 'Pets app', + }); + assert.deepEqual(await delegated.json(), { + connection_id: id, + agent: app.agent, + label: 'Pets app', + }); + + // The frame's call reaches the fixture, with its paging headers. + const first = await call('GET', '/pets'); + assert.equal(first.status, 200); assert.equal((await first.json()).length, 2); assert.match(first.headers.get('link'), /page=2/); - assert.equal((await read(result.connection_code)).status, 401); - const second = await read( - first.headers.get('x-connection-code'), - '?page=2', + assert.equal(first.headers.get('x-connection-code'), null); + assert.equal((await (await call('GET', '/pets?page=2')).json()).length, 3); + const listed = (await list(owner)).connections[0]; + assert.ok(listed.last_used_at); + assert.ok(listed.delegations[0].last_used_at); + + // The owner and the delegated app may sign requests themselves. + for (const signer of [owner, app]) + assert.equal( + (await signed(signer, 'GET', `${base}/proxy/${id}/pets/pets`)).status, + 200, + ); + assert.deepEqual( + await errorOf( + await signed(stranger, 'GET', `${base}/proxy/${id}/pets/pets`), + ), + [403, 'not_delegated'], + ); + + // A node's agent registered as a runtime of the app may too. + assert.deepEqual( + await errorOf(await signed(node, 'GET', `${base}/proxy/${id}/pets/pets`)), + [403, 'not_delegated'], + ); + const runtime = await signed(owner, 'POST', `${base}/runtimes`, { + body: JSON.stringify({ app: app.agent, agent: node.agent, label: 'n' }), + }); + assert.equal(runtime.status, 200); + assert.equal( + (await signed(node, 'GET', `${base}/proxy/${id}/pets/pets`)).status, + 200, + ); + assert.deepEqual( + (await list(owner)).runtimes.map(r => [r.agent, r.app]), + [[node.agent, app.agent]], + ); + assert.deepEqual( + await errorOf( + await signed(owner, 'POST', `${base}/runtimes`, { + body: JSON.stringify({ app: app.agent, agent: owner.agent }), + }), + ), + [400, 'bad_request'], ); - assert.equal((await second.json()).length, 3); assert.equal( ( - await fetch(`${base}/proxy/google-calendar/events`, { - headers: { - Authorization: `Bearer ${second.headers.get('x-connection-code')}`, - }, - }) + await signed( + owner, + 'DELETE', + `${base}/runtimes/${encodeURIComponent(node.agent)}`, + ) ).status, + 204, + ); + assert.deepEqual( + await errorOf(await signed(node, 'GET', `${base}/proxy/${id}/pets/pets`)), + [403, 'not_delegated'], + ); + + // Introspection for specs in another process. + const state = await (await fetch(`${base}/__mock/connections`)).json(); + assert.deepEqual( + state.connections.map(c => [c.owner, c.delegations.map(d => d.agent)]), + [[owner.agent, [app.agent]]], + ); + assert.equal(server.proxyState.connections.size, 1); + + // Revoking the delegation stops the frame at once; deleting the + // connection makes it unknown. + assert.equal( + ( + await signed( + owner, + 'DELETE', + `${base}/connections/${id}/agents/${encodeURIComponent(app.agent)}`, + ) + ).status, + 204, + ); + assert.deepEqual(await errorOf(await call('GET', '/pets')), [ + 403, + 'not_delegated', + ]); + assert.deepEqual( + await errorOf( + await signed(stranger, 'DELETE', `${base}/connections/${id}`), + ), + [403, 'not_owner'], + ); + assert.equal( + (await signed(owner, 'DELETE', `${base}/connections/${id}`)).status, + 204, + ); + assert.deepEqual(await errorOf(await call('GET', '/pets')), [ + 404, + 'unknown_connection', + ]); + } finally { + await close(); + } +}); + +test('every refusal on a proxied request has the real proxy’s code', async () => { + const { base, close } = await start({ platforms: 'pets,notion' }); + + try { + const id = await connect(base, 'pets'); + const url = `${base}/proxy/${id}/pets/pets`; + const now = Math.floor(Date.now() / 1000); + const expectError = async (response, status, code) => + assert.deepEqual(await errorOf(response), [status, code], code); + + await expectError( + await fetch(url, { headers: { Authorization: 'Bearer old-code' } }), + 401, + 'unsupported_authorization', + ); + await expectError(await fetch(url), 401, 'missing_signature'); + // v1 (no version header): never accepted. + const v1 = owner.headers('GET', url); + delete v1['x-atomic-signature-version']; + await expectError( + await fetch(url, { headers: v1 }), + 401, + 'unsupported_signature_version', + ); + await expectError( + await signed(owner, 'GET', url, { at: Date.now() - 400_000 }), + 401, + 'stale_timestamp', + ); + // Signed for another origin (e.g. `localhost` instead of the configured + // 127.0.0.1): the full URL is part of the message. + await expectError( + await fetch(url, { + headers: owner.headers('GET', url.replace('127.0.0.1', 'localhost')), + }), + 401, + 'bad_signature', + ); + const mixed = { + ...owner.headers('GET', url), + 'x-atomic-agent': stranger.agent, + }; + await expectError( + await fetch(url, { headers: mixed }), + 401, + 'agent_key_mismatch', + ); + const once = owner.headers('GET', url); + assert.equal((await fetch(url, { headers: once })).status, 200); + await expectError(await fetch(url, { headers: once }), 401, 'replayed'); + + const capabilityCases = [ + [{}, frame, 200], + [{ exp: now - 1 }, frame, [401, 'capability_expired']], + [{ exp: now + 901 + 5 }, frame, [401, 'capability_too_long']], + [{ aud: 'http://localhost:1' }, frame, [401, 'wrong_audience']], + [{ platform: 'notion' }, frame, [403, 'capability_scope']], + [{ connection_id: 'x'.repeat(43) }, frame, [403, 'capability_scope']], + [{ app: stranger.agent }, frame, [403, 'not_delegated']], + [{}, stranger, [401, 'capability_key_mismatch']], + ]; + + for (const [claims, signer, expected] of capabilityCases) { + const response = await frameClient( + base, + id, + 'pets', + claims, + )('GET', '/pets', { signer }); + if (expected === 200) assert.equal(response.status, 200); + else await expectError(response, ...expected); + } + + // Signed by someone other than the owner. + const forged = `${mintCapability(stranger, { + connection_id: id, + platform: 'pets', + aud: base, + app: app.agent, + cnf: frame.agent, + exp: now + 600, + })}`; + await expectError( + await fetch(url, { + headers: { + Authorization: `Capability ${forged}`, + ...frame.headers('GET', url), + }, + }), + 401, + 'invalid_capability', + ); + // A capability for the right connection on the wrong route's platform. + await expectError( + await signed(owner, 'GET', `${base}/proxy/${id}/notion/v1/search`), 403, + 'platform_mismatch', + ); + // fetch() would normalise the dot segment away; send it raw. + const traversal = await new Promise((resolve, reject) => + request( + { + host: '127.0.0.1', + port: new URL(base).port, + path: `/proxy/${id}/pets/%2e%2e/secret`, + }, + resolve, + ) + .on('error', reject) + .end(), + ); + assert.equal(traversal.statusCode, 400); + // A management call must be signed too. + await expectError( + await fetch(`${base}/connections`), + 401, + 'missing_signature', ); } finally { - server.closeAllConnections(); - await new Promise(resolve => server.close(resolve)); + await close(); + } +}); + +test('CORS lets a null-origin frame send the signature headers and a capability', async () => { + const { base, close } = await start({ platforms: 'pets' }); + + try { + const preflight = await fetch(`${base}/proxy/x/pets/pets`, { + method: 'OPTIONS', + headers: { + Origin: 'null', + 'Access-Control-Request-Method': 'PATCH', + 'Access-Control-Request-Headers': + 'authorization,x-atomic-signature-version', + }, + }); + assert.equal(preflight.status, 204); + assert.equal(preflight.headers.get('access-control-allow-origin'), '*'); + const allowed = preflight.headers + .get('access-control-allow-headers') + .toLowerCase(); + for (const name of [ + 'authorization', + 'content-type', + 'if-match', + 'x-atomic-agent', + 'x-atomic-public-key', + 'x-atomic-timestamp', + 'x-atomic-signature', + 'x-atomic-signature-version', + ]) + assert.ok(allowed.includes(name), name); + const exposed = preflight.headers + .get('access-control-expose-headers') + .toLowerCase(); + for (const name of ['link', 'retry-after', 'etag', 'content-type']) + assert.ok(exposed.includes(name), name); + assert.ok(!exposed.includes('x-connection-code')); + } finally { + await close(); + } +}); + +test('API-key platforms take the key on the consent page; cancel returns access_denied', async () => { + const { base, close } = await start({ platforms: 'clockify' }); + + try { + const blank = await consent(base, 'clockify'); + assert.match(blank.html, /name="api_key"/); + assert.match(blank.html, /Connect Clockify/); + assert.equal((await blank.submit()).status, 400); + + const cancelled = await consent(base, 'clockify', { cancel: '1' }); + const back = new URL((await cancelled.submit()).headers.get('location')); + assert.equal(back.searchParams.get('error'), 'access_denied'); + assert.equal(back.searchParams.get('connection_code'), null); + + assert.equal( + (await connect(base, 'clockify', { api_key: 'synthetic-key' })).length, + 43, + ); + } finally { + await close(); + } +}); + +test('test-side revoke drops a delegation or a whole connection', async () => { + const { base, close } = await start({ platforms: 'pets' }); + + try { + const id = await connect(base, 'pets'); + const call = frameClient(base, id, 'pets'); + const revoke = body => + fetch(`${base}/__mock/revoke`, { + method: 'POST', + body: JSON.stringify(body), + }); + assert.equal((await call('GET', '/pets')).status, 200); + assert.equal( + (await revoke({ connection_id: id, agent: app.agent })).status, + 200, + ); + assert.deepEqual(await errorOf(await call('GET', '/pets')), [ + 403, + 'not_delegated', + ]); + assert.equal((await revoke({ connection_id: id })).status, 200); + assert.deepEqual(await errorOf(await call('GET', '/pets')), [ + 404, + 'unknown_connection', + ]); + assert.equal((await revoke({ connection_id: id })).status, 404); + } finally { + await close(); } }); @@ -115,17 +751,7 @@ test('MOCK_PROXY_PLATFORMS restricts the catalog, consent and catalog documents' (await fetch(`${base}/catalog/clockify.selection.json`)).status, 404, ); - const url = new URL(`${base}/connect`); - url.search = new URLSearchParams({ - redirect_uri: - 'http://localhost:6747/app/integrations?integration_state=abc&platform=clockify', - platform: 'clockify', - user_id: 'synthetic-agent', - code_challenge: challenge, - code_challenge_method: 'S256', - credentials: 'connection', - }); - assert.equal((await fetch(url)).status, 400); + assert.equal((await fetch(connectUrl(base, 'clockify'))).status, 400); assert.equal(server.clockify, undefined); } finally { server.closeAllConnections(); @@ -134,18 +760,9 @@ test('MOCK_PROXY_PLATFORMS restricts the catalog, consent and catalog documents' }); test('an empty platform list serves every fixture', async () => { - const server = mockProxy({ platforms: '' }); - await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); - const base = `http://127.0.0.1:${server.address().port}`; + const { base, server, close } = await start({ platforms: '' }); try { - assert.deepEqual(await (await fetch(`${base}/catalog`)).json(), [ - 'clockify', - 'github-issues', - 'google-calendar', - 'notion', - 'pets', - ]); for (const id of ['clockify', 'google-calendar', 'notion', 'pets']) assert.equal((await fetch(`${base}/catalog/${id}.yaml`)).status, 200); assert.ok(server.github.createIssue); @@ -153,39 +770,12 @@ test('an empty platform list serves every fixture', async () => { assert.ok(server.clockify.state); assert.deepEqual(server.fixtures.notion.requests, []); } finally { - server.closeAllConnections(); - await new Promise(resolve => server.close(resolve)); + await close(); } }); -/** Connects through /connect and /connect/redeem; returns the first code. */ -async function connect(base, platform) { - const url = new URL(`${base}/connect`); - url.search = new URLSearchParams({ - redirect_uri: `http://localhost:6747/app/integrations?integration_state=abc&platform=${platform}`, - platform, - user_id: 'synthetic-agent', - code_challenge: challenge, - code_challenge_method: 'S256', - credentials: 'connection', - }); - const consent = await fetch(url, { method: 'POST', redirect: 'manual' }); - const handoff = new URL(consent.headers.get('location')).searchParams.get( - 'connection_code', - ); - const redeemed = await fetch(`${base}/connect/redeem`, { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ code: handoff, code_verifier: verifier }), - }); - - return (await redeemed.json()).connection_code; -} - test('fixture driver: POST /__fixture/ reaches control(), nothing else does', async () => { - const server = mockProxy({ platforms: 'clockify,notion' }); - await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); - const base = `http://127.0.0.1:${server.address().port}`; + const { base, server, close } = await start({ platforms: 'clockify,notion' }); const drive = (platform, command, method = 'POST') => fetch(`${base}/__fixture/${platform}`, { method, @@ -207,31 +797,20 @@ test('fixture driver: POST /__fixture/ reaches control(), nothing else status: 503, }); } finally { - server.closeAllConnections(); - await new Promise(resolve => server.close(resolve)); + await close(); } }); test('notion: POST list bodies reach the fixture; the cursor travels in the body', async () => { - const server = mockProxy({ platforms: 'notion' }); - await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); - const base = `http://127.0.0.1:${server.address().port}`; + const { base, server, close } = await start({ platforms: 'notion' }); try { const document = await (await fetch(`${base}/catalog/notion.yaml`)).json(); assert.ok(document.components.crudResources.page); - let code = await connect(base, 'notion'); + const call = frameClient(base, await connect(base, 'notion'), 'notion'); const post = async (path, body) => { - const response = await fetch(`${base}/proxy/notion${path}`, { - method: 'POST', - headers: { - Authorization: `Bearer ${code}`, - 'Content-Type': 'application/json', - }, - body: JSON.stringify(body), - }); - code = response.headers.get('x-connection-code'); + const response = await call('POST', path, { body: JSON.stringify(body) }); return { status: response.status, body: await response.json() }; }; @@ -270,18 +849,17 @@ test('notion: POST list bodies reach the fixture; the cursor travels in the body first.body.next_cursor, ); } finally { - server.closeAllConnections(); - await new Promise(resolve => server.close(resolve)); + await close(); } }); test('google-calendar: If-Match reaches the fixture, ETag comes back, CORS allows both', async () => { - const server = mockProxy({ platforms: 'google-calendar' }); - await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); - const base = `http://127.0.0.1:${server.address().port}`; + const { base, server, close } = await start({ + platforms: 'google-calendar', + }); try { - const preflight = await fetch(`${base}/proxy/google-calendar/x`, { + const preflight = await fetch(`${base}/proxy/x/google-calendar/x`, { method: 'OPTIONS', }); assert.match( @@ -293,22 +871,17 @@ test('google-calendar: If-Match reaches the fixture, ETag comes back, CORS allow /ETag/, ); - let code = await connect(base, 'google-calendar'); + const frameCall = frameClient( + base, + await connect(base, 'google-calendar'), + 'google-calendar', + ); const call = async (method, path, { body, ifMatch } = {}) => { - const response = await fetch( - `${base}/proxy/google-calendar/calendar/v3${path}`, - { - method, - headers: { - Authorization: `Bearer ${code}`, - ...(body ? { 'Content-Type': 'application/json' } : {}), - ...(ifMatch ? { 'If-Match': ifMatch } : {}), - }, - ...(body ? { body: JSON.stringify(body) } : {}), - }, - ); - code = response.headers.get('x-connection-code'); + const response = await frameCall(method, `/calendar/v3${path}`, { + ...(body ? { body: JSON.stringify(body) } : {}), + ifMatch, + }); return { status: response.status, @@ -358,19 +931,16 @@ test('google-calendar: If-Match reaches the fixture, ETag comes back, CORS allow 404, ); } finally { - server.closeAllConnections(); - await new Promise(resolve => server.close(resolve)); + await close(); } }); test('clockify: JSON write bodies reach the fixture, PUT passes CORS, a dropped response never answers', async () => { - const server = mockProxy({ platforms: 'clockify' }); - await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); - const base = `http://127.0.0.1:${server.address().port}`; + const { base, server, close } = await start({ platforms: 'clockify' }); const workspace = '/api/v1/workspaces/aaaaaaaaaaaaaaaaaaaaaaaa'; try { - const preflight = await fetch(`${base}/proxy/clockify${workspace}`, { + const preflight = await fetch(`${base}/proxy/x/clockify${workspace}`, { method: 'OPTIONS', }); assert.match( @@ -381,18 +951,16 @@ test('clockify: JSON write bodies reach the fixture, PUT passes CORS, a dropped preflight.headers.get('access-control-expose-headers'), /\bLast-Page\b/, ); - let code = await connect(base, 'clockify'); + const frameCall = frameClient( + base, + await connect(base, 'clockify', { api_key: 'synthetic-key' }), + 'clockify', + ); const call = async (method, path, body) => { - const response = await fetch(`${base}/proxy/clockify${path}`, { - method, - headers: { - Authorization: `Bearer ${code}`, - ...(body ? { 'Content-Type': 'application/json' } : {}), - }, + const response = await frameCall(method, path, { ...(body ? { body: JSON.stringify(body) } : {}), }); - code = response.headers.get('x-connection-code'); const text = await response.text(); return { @@ -438,12 +1006,7 @@ test('clockify: JSON write bodies reach the fixture, PUT passes CORS, a dropped // A write whose response is lost: applied, then no answer at all. server.clockify.control({ action: 'applyThenDrop', hang: true }); const controller = new AbortController(); - const pending = fetch(`${base}/proxy/clockify${workspace}/time-entries`, { - method: 'POST', - headers: { - Authorization: `Bearer ${code}`, - 'Content-Type': 'application/json', - }, + const pending = frameCall('POST', `${workspace}/time-entries`, { body: JSON.stringify({ start: '2026-09-02T08:00:00Z' }), signal: controller.signal, }); @@ -456,7 +1019,6 @@ test('clockify: JSON write bodies reach the fixture, PUT passes CORS, a dropped controller.abort(); await assert.rejects(pending); } finally { - server.closeAllConnections(); - await new Promise(resolve => server.close(resolve)); + await close(); } }); diff --git a/integrations/localthought/settings.test.ts b/integrations/localthought/settings.test.ts deleted file mode 100644 index 5f8bc048c..000000000 --- a/integrations/localthought/settings.test.ts +++ /dev/null @@ -1,105 +0,0 @@ -import { expect, it } from 'vitest'; -import { - configuredProxy, - importInstallationIdentity, - proxySettingKey, - readSavedConnection, - savedConnectionKey, - saveProxy, -} from './settings'; - -function storage() { - const values = new Map(); - - return { - getItem: (key: string) => values.get(key) ?? null, - setItem: (key: string, value: string) => { - values.set(key, value); - }, - removeItem: (key: string) => { - values.delete(key); - }, - }; -} - -it('persists a runtime proxy override and resets to the deployment default', () => { - const s = storage(); - expect(configuredProxy(s, 'https://deployment.example')).toBe( - 'https://deployment.example', - ); - saveProxy(s, ' https://custom.example/ '); - expect(configuredProxy(s)).toBe('https://custom.example'); - saveProxy(s, ''); - expect(configuredProxy(s, 'https://deployment.example')).toBe( - 'https://deployment.example', - ); -}); -it('rejects invalid URLs without overwriting the working setting', () => { - const s = storage(); - saveProxy(s, 'http://localhost:19090'); - for (const value of [ - 'https://example.com/path', - 'http://example.com', - 'https://user:password@example.com', - 'garbage', - ]) - expect(() => saveProxy(s, value)).toThrow(); - expect(s.getItem(proxySettingKey)).toBe('http://localhost:19090'); -}); -it('keeps the same platform on two proxies separate', () => { - expect( - savedConnectionKey('https://a.example', 'drive', 'actor', 'github'), - ).not.toBe( - savedConnectionKey('https://b.example', 'drive', 'actor', 'github'), - ); -}); -it('migrates legacy connections only for the matching proxy and owner', () => { - const s = storage(); - const saved = JSON.stringify({ - connection: 'state', - platform: 'github', - drive: 'drive', - actor: 'actor', - }); - s.setItem('localthought-browser:["drive","actor","github"]', saved); - s.setItem( - 'localthought-browser-v1:state', - JSON.stringify({ - origin: 'https://a.example', - drive: 'drive', - actor: 'actor', - platform: 'github', - }), - ); - expect( - readSavedConnection(s, 'https://b.example', 'drive', 'actor', 'github'), - ).toBeUndefined(); - expect( - readSavedConnection(s, 'https://a.example', 'drive', 'actor', 'github'), - ).toBe(saved); - expect( - s.getItem( - savedConnectionKey('https://a.example', 'drive', 'actor', 'github'), - ), - ).toBe(saved); -}); - -it('isolates reconnects even when a legacy installation identity is present', () => { - const previous = { connection: 'old' }; - const reconnected = { connection: 'new', installationConnection: 'old' }; - const options = { calendar: 'primary' }; - expect(importInstallationIdentity(reconnected, options)).not.toBe( - importInstallationIdentity(previous, options), - ); - expect(importInstallationIdentity(reconnected, options)).toBe( - importInstallationIdentity({ connection: 'new' }, options), - ); -}); -it('reuses an installation for repeated imports with the same connection and options', () => { - const connection = { connection: 'same-account-session' }; - expect( - importInstallationIdentity(connection, { a: '1', b: '2' }, ':selection'), - ).toBe( - importInstallationIdentity(connection, { b: '2', a: '1' }, ':selection'), - ); -}); diff --git a/integrations/localthought/settings.ts b/integrations/localthought/settings.ts deleted file mode 100644 index 8d426b1bf..000000000 --- a/integrations/localthought/settings.ts +++ /dev/null @@ -1,81 +0,0 @@ -/** Browser-local proxy preferences and origin-scoped connection discovery. */ -import { DEFAULT_PROXY, proxyOrigin } from './browser'; - -export const proxySettingKey = 'integration-proxy-url'; - -export function configuredProxy( - storage: Pick, - fallback = DEFAULT_PROXY, -) { - return proxyOrigin(storage.getItem(proxySettingKey) || fallback); -} - -export function saveProxy( - storage: Pick, - value: string, -) { - const trimmed = value.trim(); - - if (!trimmed) { - storage.removeItem(proxySettingKey); - - return; - } - - const origin = proxyOrigin(trimmed.replace(/\/$/, '')); - storage.setItem(proxySettingKey, origin); -} - -export function savedConnectionKey( - origin: string, - drive: string, - actor: string, - platform: string, -) { - return `localthought-browser:${JSON.stringify([proxyOrigin(origin), drive, actor, platform])}`; -} - -export function readSavedConnection( - storage: Pick, - origin: string, - drive: string, - actor: string, - platform: string, -) { - const key = savedConnectionKey(origin, drive, actor, platform); - const current = storage.getItem(key); - if (current) return current; - const legacy = storage.getItem( - `localthought-browser:${JSON.stringify([drive, actor, platform])}`, - ); - if (!legacy) return; - - try { - const saved = JSON.parse(legacy); - const credential = JSON.parse( - storage.getItem(`localthought-browser-v1:${saved.connection}`) || 'null', - ); - if ( - credential?.origin !== origin || - credential.drive !== drive || - credential.actor !== actor || - credential.platform !== platform - ) - return; - storage.setItem(key, legacy); - - return legacy; - } catch { - return; - } -} - -/** The proxy does not attest account identity. Each OAuth connection must own - * a separate installation, including reconnects and legacy saved connections. */ -export function importInstallationIdentity( - connection: { connection: string }, - constants: Record, - selectionSuffix = '', -) { - return `localthought:${connection.connection}:${JSON.stringify(Object.entries(constants).sort())}${selectionSuffix}`; -} From 175dde77c6c8064dec959e253fb2433e77b6fe25 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 24 Sep 2026 16:59:59 +0200 Subject: [PATCH 2/8] Remove the rotating-code proxy clients; new no-credentials rules (#54 phase 2) Deleted, since connection codes no longer exist and nothing in this repo or the pinned atomic-server imports them (atomic-server's helpers/proxyConnections.ts replaced them): - integrations/localthought/browser.ts, browser.test.ts (BrowserIntegrations: rotating-code client) - integrations/localthought/settings.ts, settings.test.ts - integrations/localthought/browser-smoke.mjs issue-tracker's devonian proxyTransport is dispatch-only now (no getCode/setCode, Bearer or X-Connection-Code branch); background.mjs classifies a connection no longer delegated to the app as needing a person. no-credentials-in-graph.test.mjs: no graph property naming a connection code, capability or code verifier; no x-connection-code anywhere shipped; no request signing or capability minting in plugin code. Co-Authored-By: Claude Opus 5.5 --- integrations/issue-tracker/app/build.test.ts | 6 +- integrations/issue-tracker/app/sync.ts | 8 - .../devonian/github-issues/README.md | 22 +-- .../devonian/github-issues/background.mjs | 10 +- .../github-issues/background.test.mjs | 3 +- .../devonian/github-issues/proxy.mjs | 117 ++++--------- .../devonian/github-issues/proxy.test.mjs | 122 ++++--------- .../no-credentials-in-graph.test.mjs | 164 ++++++++---------- integrations/localthought/tsconfig.json | 8 +- 9 files changed, 163 insertions(+), 297 deletions(-) diff --git a/integrations/issue-tracker/app/build.test.ts b/integrations/issue-tracker/app/build.test.ts index 51b9bea9d..823797590 100644 --- a/integrations/issue-tracker/app/build.test.ts +++ b/integrations/issue-tracker/app/build.test.ts @@ -28,9 +28,9 @@ describe('GitHub issues drive-app bundle', async () => { expect(text).not.toMatch(/\bfetch\(/); expect(text).not.toMatch(/navigator\.locks/); expect(text).not.toMatch(/node:/); - // proxyTransport's own code-spending branch is bundled but unreachable: - // sync.ts always passes `dispatch`, and its getCode/setCode throw. - expect(text).toMatch(/The host holds the connection code/); + // No connection codes any more (#54 phase 2): proxyTransport only + // dispatches through the host. + expect(text).not.toMatch(/x-connection-code|getCode|setCode/i); }); it("bundles devonian's Atomic Data API and reconcileRecord only", () => { diff --git a/integrations/issue-tracker/app/sync.ts b/integrations/issue-tracker/app/sync.ts index 1a9b63734..1b97d3152 100644 --- a/integrations/issue-tracker/app/sync.ts +++ b/integrations/issue-tracker/app/sync.ts @@ -197,17 +197,9 @@ function bridgeFor(options: PassOptions) { commentsFolder: tracker.commentsFolder, }); const transport = proxyTransport({ - // Only checked for shape: every request goes through `dispatch`. - url: 'https://api.github.com', repository, journal: state.state.journal, save: () => state.saveJournal(), - getCode: () => { - throw new Error('The host holds the connection code'); - }, - setCode: () => { - throw new Error('The host holds the connection code'); - }, dispatch: options.dispatch ?? relayDispatch(options.proxy, options.connectionId), }); diff --git a/integrations/issue-tracker/devonian/github-issues/README.md b/integrations/issue-tracker/devonian/github-issues/README.md index f816f4c79..1fc2a5400 100644 --- a/integrations/issue-tracker/devonian/github-issues/README.md +++ b/integrations/issue-tracker/devonian/github-issues/README.md @@ -49,12 +49,10 @@ README) with this lens's error classification. per connection). Pass the IndexedDB database that already holds the bridge snapshot and transport journal, so every context sees the same schedule. - Every pass holds a lease (`navigator.locks` by default, so it is shared by - tabs and the service worker and released when a context dies). The - rotating proxy code is single-use, so everything else that spends it — - a manual "Sync now", an interactive write — must go through - `sync.withLock(fn)` or `sync.syncNow()`. `proxyTransport`'s - `getCode`/`setCode` may be async so the code can live in that same - IndexedDB database. `sessionStorage` is invisible to a service worker. + tabs and the service worker and released when a context dies). Run a + manual "Sync now" or an interactive write through `sync.withLock(fn)` or + `sync.syncNow()` too, so two contexts never write the same connection at + once. `sessionStorage` is invisible to a service worker. - Transient failures back off exponentially: `intervalMs`, then 2×, 4×, …, up to `maxBackoffMs` (default: one hour, or `intervalMs` if that is longer). Failures that need a person pause the schedule until `resume()`: @@ -62,8 +60,9 @@ README) with this lens's error classification. `Missing … record`, `State belongs to another connection`, `Duplicate …`; the Atomic port's `Recovered Atomic create was edited` and `Atomic write rejected`; and the transport's `Uncertain GitHub write`, - `Operation identity reused`, a missing or unexposed connection code, and - GitHub `401`. The list is `permanentSyncErrors`. Nothing is retried in a + `Operation identity reused`, a connection that is no longer delegated to + the app (`No … connection … is delegated to this app`), and GitHub + `401`. The list is `permanentSyncErrors`. Nothing is retried in a loop, and neither side is modified while paused. A browser host wires three triggers into the same `BackgroundSync`: @@ -269,8 +268,11 @@ The current host is the issue-tracker **drive app** ([`../../app/`](../../app/), see the plugin README's "Drive app"). It runs this Bridge unchanged in the host's null-origin frame: -- `proxyTransport` with `dispatch` over the host relay - (`store.proxy.request`), so the frame never holds a connection code. +- `proxyTransport` with `dispatch` over the host's `store.proxy.request`. + Since ontola/atomic-plugins#54 phase 2 the frame calls the integration + proxy itself, with a short-lived capability from the host page and a key + only the host's frame client holds; this lens never sees a credential. + `proxyTransport` has no other transport any more. - `AtomicPort` over an adapter (`app/frameStore.ts`) that gives the frame's `PluginStore` the store predicates `target.mjs` reads, and corrects for the host's reads lagging the app's own writes. diff --git a/integrations/issue-tracker/devonian/github-issues/background.mjs b/integrations/issue-tracker/devonian/github-issues/background.mjs index 82511b4d5..d6dd0db8d 100644 --- a/integrations/issue-tracker/devonian/github-issues/background.mjs +++ b/integrations/issue-tracker/devonian/github-issues/background.mjs @@ -16,9 +16,9 @@ export const permanentSyncErrors = [ /^Atomic write rejected/, /^Uncertain GitHub write/, /^Operation identity reused/, - // The rotating proxy code is gone or revoked: reconnect first. - /^Connect to the proxy or supply a fresh connection code/, - /^Proxy did not expose X-Connection-Code/, + // The connection is gone or no longer delegated to this app (the host's + // check before it mints a capability): reconnect first. + /^No [a-z0-9-]+ connection .* is delegated to this app/, /^GitHub \S+ returned 401$/, ]; @@ -33,8 +33,8 @@ export const isPermanentSyncError = error => * `openBridge` must build a new Bridge from the persisted snapshot on every * call: a tab, a service worker or another host may have synced since the * last pass, and a cached Bridge would reconcile from a stale checkpoint. - * Every pass runs under the schedule's lease (`withLock`); a host must put - * any other spend of the same connection's rotating proxy code under it too. + * Every pass runs under the schedule's lease (`withLock`), so two contexts + * never sync the same connection at once. */ export function createBackgroundSync({ openBridge, diff --git a/integrations/issue-tracker/devonian/github-issues/background.test.mjs b/integrations/issue-tracker/devonian/github-issues/background.test.mjs index 6093c851d..2437c32a3 100644 --- a/integrations/issue-tracker/devonian/github-issues/background.test.mjs +++ b/integrations/issue-tracker/devonian/github-issues/background.test.mjs @@ -183,8 +183,7 @@ it('classifies human-action failures as permanent and everything else as transie 'Atomic write rejected: forbidden', 'Uncertain GitHub write (create_issue). Inspect its outcome before retrying; it will not be resent.', 'Operation identity reused with different arguments', - 'Connect to the proxy or supply a fresh connection code', - 'Proxy did not expose X-Connection-Code. Enable CORS exposure and reconnect.', + 'No github-issues connection abc is delegated to this app. Connect again.', 'GitHub list_issues returned 401', ]) expect(isPermanentSyncError(new Error(message)), message).toBe(true); diff --git a/integrations/issue-tracker/devonian/github-issues/proxy.mjs b/integrations/issue-tracker/devonian/github-issues/proxy.mjs index 5906d5956..291351296 100644 --- a/integrations/issue-tracker/devonian/github-issues/proxy.mjs +++ b/integrations/issue-tracker/devonian/github-issues/proxy.mjs @@ -2,30 +2,25 @@ import { endpoint, request } from './adapter.js'; import { trackerAction } from './tracker-actions.js'; /** - * Direct browser transport. Codes stay in browser storage, never in Atomic - * resources. `getCode`/`setCode` may be async, so a host can keep the code in - * IndexedDB shared with a service worker; every spend must then run under one - * cross-context lease (see background.mjs), because each code is single-use. + * GitHub issue actions over the integration proxy, through `dispatch`. + * + * `dispatch(path, { method, body })` makes one proxy call for a GitHub API + * path (`/repos/{owner}/{name}/issues…`, query included) and resolves to + * `{ status, body }`. In the drive app it is the host's + * `store.proxy.request` (see `app/transport.ts`): since + * ontola/atomic-plugins#54 phase 2 the plugin frame calls the proxy itself + * with a capability from the page and a key only it holds, so this module + * never sees a credential. The direct transport this used to have, which + * spent a rotating connection code per request (`getCode`/`setCode`), went + * with the proxy's connection codes. + * + * Writes are journalled before they leave (`journal[id]`, persisted by + * `save`), so a write whose outcome is unknown is never resent. Calls are + * serialised, one at a time. */ -export function proxyTransport({ - url, - repository, - getCode, - setCode, - journal, - save, - fetcher = fetch, - dispatch, -}) { - const origin = new URL(url); - if ( - origin.protocol !== 'https:' && - !( - origin.protocol === 'http:' && - ['localhost', '127.0.0.1'].includes(origin.hostname) - ) - ) - throw new Error('Use an HTTPS proxy or loopback HTTP'); +export function proxyTransport({ repository, journal, save, dispatch }) { + if (typeof dispatch !== 'function') + throw new Error('proxyTransport needs a dispatch function'); const root = endpoint(repository); let pending = Promise.resolve(); @@ -71,72 +66,34 @@ export function proxyTransport({ } const target = new URL(intent.url); - let receipt; - let next = true; - - if (dispatch) { - receipt = await dispatch(`${target.pathname}${target.search}`, { - method: intent.method, - ...(intent.body ? { body: intent.body } : {}), - }).catch(async error => { - // A dispatcher that knows the request never left (e.g. the host - // refused it before spending a connection code) says so with - // `notSent`; only then is the journal entry dropped, so the write - // is not stuck as uncertain. Anything else stays uncertain. - if (error?.notSent) { - if (writes) { - delete journal[id]; - await save(); - } - - throw error; + const receipt = await dispatch(`${target.pathname}${target.search}`, { + method: intent.method, + ...(intent.body ? { body: intent.body } : {}), + }).catch(async error => { + // A dispatcher that knows the request never left (e.g. the host + // refused to mint a capability, or the browser cannot make the + // frame key) says so with `notSent`; only then is the journal entry + // dropped, so the write is not stuck as uncertain. Anything else + // stays uncertain. + if (error?.notSent) { + if (writes) { + delete journal[id]; + await save(); } - throw new Error( - `Proxy request failed (${error?.message ?? error}). Check CORS and reconnect; an uncertain write will not be resent.`, - ); - }); - } else { - const code = await getCode(); - if (!code) - throw new Error( - 'Connect to the proxy or supply a fresh connection code', - ); - await setCode(''); - const destination = new URL( - `/proxy/github-issues${target.pathname}${target.search}`, - origin, + throw error; + } + + throw new Error( + `Proxy request failed (${error?.message ?? error}). Check CORS and reconnect; an uncertain write will not be resent.`, ); - const response = await fetcher(destination.href, { - method: intent.method, - redirect: 'error', - credentials: 'omit', - headers: { - Authorization: `Bearer ${code}`, - Accept: 'application/vnd.github+json', - 'Content-Type': 'application/json', - }, - ...(intent.body ? { body: intent.body } : {}), - }).catch(() => { - throw new Error( - 'Proxy request failed. Check CORS and reconnect; an uncertain write will not be resent.', - ); - }); - next = response.headers.get('X-Connection-Code'); - if (next) await setCode(next); - receipt = { status: response.status, body: await response.text() }; - } + }); if (writes && receipt.status >= 200 && receipt.status < 300) { journal[id].receipt = receipt; await save(); } - if (!next) - throw new Error( - 'Proxy did not expose X-Connection-Code. Enable CORS exposure and reconnect.', - ); - return receipt; }; diff --git a/integrations/issue-tracker/devonian/github-issues/proxy.test.mjs b/integrations/issue-tracker/devonian/github-issues/proxy.test.mjs index 9b5f46758..df1a286b0 100644 --- a/integrations/issue-tracker/devonian/github-issues/proxy.test.mjs +++ b/integrations/issue-tracker/devonian/github-issues/proxy.test.mjs @@ -1,42 +1,45 @@ import { expect, it } from 'vitest'; import { proxyTransport } from './proxy.mjs'; -it('serializes rotating codes, preserves query strings and checkpoints successful writes', async () => { - let code = 'first'; +it('needs a dispatch function: there is no direct, code-spending transport any more', () => { + expect(() => + proxyTransport({ + repository: 'owner/repo', + journal: {}, + save: async () => {}, + }), + ).toThrow('dispatch'); +}); + +it('serializes calls, preserves query strings and checkpoints successful writes', async () => { const seen = []; const journal = {}; let saves = 0; + let inFlight = 0; const call = proxyTransport({ - url: 'https://proxy.example', repository: 'owner/repo', journal, - getCode: () => code, - setCode: c => { - code = c; - }, save: async () => { saves++; }, - fetcher: async (url, opts) => { - seen.push({ url, ...opts }); + dispatch: async (path, init) => { + expect(inFlight).toBe(0); + inFlight++; + seen.push({ path, ...init }); + await new Promise(resolve => setTimeout(resolve, 0)); + inFlight--; - return new Response('{"id":1}', { - headers: { 'X-Connection-Code': `next-${seen.length}` }, - }); + return { status: 200, body: '{"id":1}' }; }, }); await Promise.all([ call('list_issues', { page: 2 }, 'read'), call('create_comment', { number: 1, body: 'Hello' }, 'write'), ]); - expect(seen[0].url).toContain( - '/proxy/github-issues/repos/owner/repo/issues?state=all&per_page=100&page=2', + expect(seen[0].path).toContain( + '/repos/owner/repo/issues?state=all&per_page=100&page=2', ); - expect(seen.map(r => r.headers.Authorization)).toEqual([ - 'Bearer first', - 'Bearer next-1', - ]); - expect(code).toBe('next-2'); + expect(seen[1].method).toBe('POST'); expect(saves).toBe(2); await call('create_comment', { number: 1, body: 'Hello' }, 'write'); expect(seen).toHaveLength(2); @@ -48,107 +51,42 @@ it('serializes rotating codes, preserves query strings and checkpoints successfu it('never retries an uncertain create after a lost response or restart', async () => { const journal = {}; let writes = 0; - let code = 'first'; const options = { - url: 'https://proxy.example', repository: 'owner/repo', journal, - getCode: () => code, - setCode: c => { - code = c; - }, save: async () => {}, - fetcher: async () => { + dispatch: async () => { writes++; - throw new Error('network'); + throw new Error('Failed to fetch'); }, }; await expect( proxyTransport(options)('create_issue', { title: 'Title' }, 'create'), ).rejects.toThrow('Proxy request failed'); - code = 'reconnected'; await expect( proxyTransport(options)('create_issue', { title: 'Title' }, 'create'), ).rejects.toThrow('Uncertain GitHub write'); expect(writes).toBe(1); }); -it('retains rotated codes on provider errors and identifies missing exposed headers', async () => { - let code = 'first'; - const options = { - url: 'https://proxy.example', +it('passes provider errors through as receipts', async () => { + const receipt = await proxyTransport({ repository: 'owner/repo', journal: {}, - getCode: () => code, - setCode: c => { - code = c; - }, save: async () => {}, - fetcher: async () => - new Response('{}', { - status: 403, - headers: { 'X-Connection-Code': 'rotated' }, - }), - }; - expect( - (await proxyTransport(options)('get_issue', { number: 1 }, 'read')).status, - ).toBe(403); - expect(code).toBe('rotated'); - options.fetcher = async () => new Response('{}'); - await expect( - proxyTransport(options)('get_issue', { number: 1 }, 'read'), - ).rejects.toThrow('expose X-Connection-Code'); + dispatch: async () => ({ status: 403, body: '{}' }), + })('get_issue', { number: 1 }, 'read'); + expect(receipt.status).toBe(403); }); -it('accepts async code storage, e.g. IndexedDB shared with a service worker', async () => { - const idb = new Map([['code', 'first']]); - const tick = () => new Promise(resolve => setTimeout(resolve, 0)); - const sent = []; - const call = proxyTransport({ - url: 'https://proxy.example', - repository: 'owner/repo', - journal: {}, - getCode: async () => { - await tick(); - - return idb.get('code'); - }, - setCode: async c => { - await tick(); - idb.set('code', c); - }, - save: async () => {}, - fetcher: async (_url, opts) => { - sent.push(opts.headers.Authorization); - - return new Response('[]', { - headers: { 'X-Connection-Code': `next-${sent.length}` }, - }); - }, - }); - await Promise.all([ - call('list_issues', { page: 1 }, 'a'), - call('list_issues', { page: 2 }, 'b'), - ]); - expect(sent).toEqual(['Bearer first', 'Bearer next-1']); - expect(idb.get('code')).toBe('next-2'); -}); - -it('dispatches through a host relay without handling a code, and journals its writes', async () => { +it('dispatches through the host without handling a credential, and journals its writes', async () => { const journal = {}; const sent = []; let failure; const call = proxyTransport({ - url: 'https://proxy.example', repository: 'owner/repo', journal, save: async () => {}, - getCode: () => { - throw new Error('a relay never reads a code'); - }, - setCode: () => { - throw new Error('a relay never writes a code'); - }, dispatch: async (path, init) => { sent.push([init.method, path]); if (failure) throw failure; diff --git a/integrations/localthought/no-credentials-in-graph.test.mjs b/integrations/localthought/no-credentials-in-graph.test.mjs index 08699cd7e..69b6ad69a 100644 --- a/integrations/localthought/no-credentials-in-graph.test.mjs +++ b/integrations/localthought/no-credentials-in-graph.test.mjs @@ -1,25 +1,34 @@ /** - * Guard for ontola/atomic-plugins#21: a LocalThought rotating connection code - * is a live bearer credential and must never become Atomic graph data. + * Guard for ontola/atomic-plugins#21 and #54: nothing that grants access to a + * provider through the integration proxy may become Atomic graph data, and + * plugin code must not do the host's signing. * - * `browser.ts` is the one sanctioned owner of the code: it keeps it in the - * browser's `Storage` (localStorage), outside the synced graph, and never - * returns it to callers. An unmerged Phase 2 of the Clockify drive plugin - * (branch `claude/hopeful-hawking-kqlrdy`, `integrations/clockify/app/src/ - * App.tsx:14,47-50`) instead read the rotated `x-connection-code` header - * (`proxyClient.ts:51`) and saved it as a `.../properties/connection-code` - * property on the plugin's App resource, i.e. into a commit that syncs and - * can later be shared with the drive. This test fails if either half of that - * pattern appears in shipped source under `integrations/`. + * Since #54 phase 2 there are no rotating connection codes any more. The + * proxy account is the user's Atomic agent; a connection lives at the proxy; + * the data browser page signs its own calls with the user key; a plugin + * frame gets a short-lived capability from the page and signs each request + * with a key only it holds (atomic-server's `view-client.js`). None of that + * belongs in a plugin's source or in the drive. The rules: + * + * 1. **No credential-shaped graph property.** A property URL that names a + * connection code, a capability or a PKCE code verifier. (An unmerged + * Clockify drive plugin once saved the rotated code as + * `.../properties/connection-code`, into a commit that syncs.) A + * connection *id* is a reference, not a credential, and is allowed. + * 2. **No retired rotation header.** `x-connection-code` carried the next + * rotating code; nothing may read or send it any more. + * 3. **No request signing or capability minting in plugin code.** The + * `x-atomic-signature` header and the capability's signed prefix + * (`integration-proxy-capability-v2`) belong to the host (atomic-server's + * page and `view-client.js`) and to the proxy. The mock proxy's own + * verifier (`mock-proxy-auth.mjs`) is a `mock-*` file and skipped. * * Scope and limits, stated exactly: this is a line-by-line text scan of - * `.ts`/`.tsx`/`.js`/`.mjs` files, not a data-flow analysis. It catches a - * property URL naming a connection code and any mention of the rotation - * header outside `browser.ts`; it does not catch a code saved under an - * unrelated property name after being obtained some other way. Tests - * (`*.test.*`, `*.spec.*`), `e2e/` directories, `mock-*` servers, - * `node_modules` and `dist` are skipped, since they legitimately emit or - * inspect the header. + * `.ts`/`.tsx`/`.js`/`.mjs` files, not a data-flow analysis. It does not + * catch a credential saved under an unrelated property name after being + * obtained some other way. Tests (`*.test.*`, `*.spec.*`), `e2e/` + * directories, `mock-*` servers, `node_modules` and `dist` are skipped, + * since they legitimately emit or inspect these values. * * Plain `node --test`, no dependencies, so it runs in this repo's own CI * ("Tooling unit tests" in .github/workflows/ci.yml) without an @@ -35,29 +44,6 @@ import { fileURLToPath } from 'node:url'; const integrationsRoot = fileURLToPath(new URL('..', import.meta.url)); -/** The primary owner of the rotated code (posix path relative to `integrations/`). */ -const CODE_OWNER = 'localthought/browser.ts'; - -/** - * Files allowed to handle the rotated code besides `CODE_OWNER`, each with the - * reason. They must hand the code only to host-provided storage (session or - * IndexedDB), never to a synced resource. - */ -const OTHER_CODE_HANDLERS = new Map([ - [ - // The Devonian GitHub issues proxy client rotates the code through the - // host's `getCode`/`setCode` (moved here from devonian/ in the - // plugin-folder containment change). - 'issue-tracker/devonian/github-issues/proxy.mjs', - 'rotates via host-provided getCode/setCode', - ], - [ - // Only matches proxy.mjs's error message to classify it as needing a person. - 'issue-tracker/devonian/github-issues/background.mjs', - 'matches an error message, holds no code', - ], -]); - const SKIPPED_DIRS = new Set([ 'node_modules', 'dist', @@ -67,32 +53,29 @@ const SKIPPED_DIRS = new Set([ const SOURCE = /\.(ts|tsx|js|mjs)$/; const NOT_SHIPPED = /(\.test\.|\.spec\.|(^|\/)mock-[^/]*$)/; -/** A graph property whose name says it holds a connection code. */ -const CODE_PROPERTY = /\/properties\/[^\s'"`]*connection[-_]?code/i; -/** The proxy's rotation header, whose value is the next live code. */ -const ROTATION_HEADER = /x-connection-code/i; +const RULES = [ + { + rule: 'credential-shaped property', + /** A graph property whose name says it holds a code, capability or verifier. */ + pattern: + /\/properties\/[^\s'"`]*(connection[-_]?code|capabilit|code[-_]?verifier)/i, + }, + { + rule: 'retired rotation header', + pattern: /x-connection-code/i, + }, + { + rule: 'host signing in plugin code', + pattern: /x-atomic-signature|integration-proxy-capability-v2/i, + }, +]; export function findCredentialLeaks(file, source) { const leaks = []; source.split('\n').forEach((text, index) => { - if (CODE_PROPERTY.test(text)) - leaks.push({ - file, - line: index + 1, - rule: 'connection-code property', - text: text.trim(), - }); - if ( - file !== CODE_OWNER && - !OTHER_CODE_HANDLERS.has(file) && - ROTATION_HEADER.test(text) - ) - leaks.push({ - file, - line: index + 1, - rule: 'rotation header outside browser.ts', - text: text.trim(), - }); + for (const { rule, pattern } of RULES) + if (pattern.test(text)) + leaks.push({ file, line: index + 1, rule, text: text.trim() }); }); return leaks; @@ -109,7 +92,7 @@ function shippedSources(dir) { }); } -test('flags the Phase 2 Clockify App.tsx/proxyClient.ts pattern', () => { +test('flags the old Clockify App.tsx/proxyClient.ts pattern', () => { const phase2 = [ " connectionCode: 'https://atomicdata.dev/integrations/clockify/properties/connection-code',", " const nextCode = response.headers.get('x-connection-code');", @@ -121,30 +104,31 @@ test('flags the Phase 2 Clockify App.tsx/proxyClient.ts pattern', () => { l.rule, ]), [ - [1, 'connection-code property'], - [2, 'rotation header outside browser.ts'], + [1, 'credential-shaped property'], + [2, 'retired rotation header'], ], ); }); -test('flags the underscore spelling of the property', () => { - assert.equal( - findCredentialLeaks( - 'x/app.ts', - "set('https://example.com/properties/proxy_connection_code', c)", - ).length, - 1, - ); +test('flags the underscore spelling, a capability and a verifier property', () => { + for (const line of [ + "set('https://example.com/properties/proxy_connection_code', c)", + "set('https://example.com/properties/proxy-capability', token)", + "set('https://example.com/properties/code_verifier', v)", + ]) + assert.equal(findCredentialLeaks('x/app.ts', line).length, 1, line); }); -test('lets browser.ts read the rotation header', () => { - assert.deepEqual( - findCredentialLeaks( - CODE_OWNER, - "const next = response.headers.get('x-connection-code');", - ), - [], - ); +test('flags a plugin that signs requests or mints capabilities itself', () => { + for (const line of [ + "headers['x-atomic-signature'] = await sign(message);", + "const prefix = 'integration-proxy-capability-v2\\n';", + ]) + assert.deepEqual( + findCredentialLeaks('pets/app/transport.ts', line).map(l => l.rule), + ['host signing in plugin code'], + line, + ); }); test('allows a non-secret connection reference', () => { @@ -157,17 +141,17 @@ test('allows a non-secret connection reference', () => { ); }); -test('the walk reaches the code owner, so it is not silently empty', () => { - assert.ok(shippedSources(integrationsRoot).includes(CODE_OWNER)); -}); - -test('every allow-listed code handler still exists', () => { +test('the walk reaches plugin sources, so it is not silently empty', () => { const sources = shippedSources(integrationsRoot); - for (const file of OTHER_CODE_HANDLERS.keys()) - assert.ok(sources.includes(file), `${file} is allow-listed but not found`); + for (const file of [ + 'pets/app/transport.ts', + 'issue-tracker/devonian/github-issues/proxy.mjs', + ]) + assert.ok(sources.includes(file), file); + assert.ok(!sources.includes('localthought/mock-proxy-auth.mjs')); }); -test('no shipped source persists or handles a rotating connection code outside browser.ts', () => { +test('no shipped source persists a credential, uses the rotation header or signs for the host', () => { const leaks = shippedSources(integrationsRoot).flatMap(file => findCredentialLeaks( file, diff --git a/integrations/localthought/tsconfig.json b/integrations/localthought/tsconfig.json index fecbd3580..a8648b3cf 100644 --- a/integrations/localthought/tsconfig.json +++ b/integrations/localthought/tsconfig.json @@ -8,11 +8,5 @@ "types": ["node"], "noEmit": true }, - "include": [ - "calendar.ts", - "calendar-sync.ts", - "schema.ts", - "plugin.ts", - "browser.ts" - ] + "include": ["calendar.ts", "calendar-sync.ts", "schema.ts", "plugin.ts"] } From 12d296218de59d831d4733da5b7f6623af06c539 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 24 Sep 2026 17:05:37 +0200 Subject: [PATCH 3/8] Drive apps: direct proxy calls with capabilities, and "use existing connection" (#54 phase 2) store.proxy keeps its shape, so the apps change little: - store.ts (each plugin's copy): connect() may now resolve {status: 'connected', connectionId, platform} when the person picks a connection they already have (no reload); PUT is a valid method; docs describe the frame key + capability flow instead of the relay and its rotating code. - Controllers reload their connections on `connected`. - Transports throw the integration proxy's own refusals ({error, message} with an api_error.rs code; answered before the provider) instead of handing them on as the provider's answer; a lost delegation or deleted connection says "Connect again". - issue-tracker: "not sent" host errors are the new host's (capability refused, no Ed25519, no app identity), and proxy refusals are marked notSent. - calendar: a lost write response no longer spends the connection (there are no codes to spend); the fake store models the new host and proxy. Co-Authored-By: Claude Opus 5.5 --- integrations/calendar/app/controller.ts | 9 +- integrations/calendar/app/fakeStore.ts | 33 +++++--- integrations/calendar/app/relay.ts | 76 ++++++++++++++--- integrations/calendar/app/store.ts | 38 ++++++--- integrations/calendar/app/sync.test.ts | 21 +++-- integrations/calendar/app/sync.ts | 11 ++- integrations/issue-tracker/app/controller.ts | 9 +- integrations/issue-tracker/app/fakeStore.ts | 9 ++ integrations/issue-tracker/app/store.ts | 35 +++++--- integrations/issue-tracker/app/sync.test.ts | 24 +++++- integrations/issue-tracker/app/transport.ts | 88 +++++++++++++++++--- integrations/notion/app/controller.ts | 10 ++- integrations/notion/app/store.ts | 35 +++++--- integrations/notion/app/transport.ts | 70 ++++++++++++++-- integrations/pets/app/controller.ts | 9 +- integrations/pets/app/store.ts | 35 ++++++-- integrations/pets/app/sync.test.ts | 27 ++++++ integrations/pets/app/transport.ts | 61 +++++++++++++- integrations/timesheets/app/controller.ts | 12 ++- integrations/timesheets/app/store.ts | 34 +++++--- integrations/timesheets/app/sync.test.ts | 20 +++++ integrations/timesheets/app/transport.ts | 77 ++++++++++++++--- 22 files changed, 606 insertions(+), 137 deletions(-) diff --git a/integrations/calendar/app/controller.ts b/integrations/calendar/app/controller.ts index 42452310b..ad0105300 100644 --- a/integrations/calendar/app/controller.ts +++ b/integrations/calendar/app/controller.ts @@ -186,10 +186,11 @@ export function createController( set({ kind: 'connecting' }); try { - // On consent the host navigates away and this view reloads; the - // promise only settles when the person cancels. - await proxy.connect({ platform: PLATFORM }); - set({ kind: 'disconnected' }); + // Connecting a new account navigates away and reloads this view; + // picking an existing one resolves `connected`, with no reload. + const result = await proxy.connect({ platform: PLATFORM }); + if (result?.status === 'connected') await controller.load(); + else set({ kind: 'disconnected' }); } catch (error) { fail(error); } diff --git a/integrations/calendar/app/fakeStore.ts b/integrations/calendar/app/fakeStore.ts index 4771d3255..862a8ab4c 100644 --- a/integrations/calendar/app/fakeStore.ts +++ b/integrations/calendar/app/fakeStore.ts @@ -4,10 +4,12 @@ * out the way `createApp` lays out an app: app -> ontology -> row class, and * app -> table. `proxy` answers from the same stateful Google Calendar * fixture the mock integration proxy serves - * (`../fixtures/google-calendar/scenario.mjs`), the way the page relays: - * `ifMatch` becomes an `If-Match` header, and a connection whose call threw - * is spent until the person reconnects (atomic-server - * `helpers/proxyConnections.ts`). Test-only; not bundled. + * (`../fixtures/google-calendar/scenario.mjs`), the way the host's frame + * client and the integration proxy answer (ontola/atomic-plugins#54): + * `ifMatch` becomes an `If-Match` header; a connection the page no longer + * lists throws the page's "Connect again" refusal; a revoked one gets the + * proxy's `403 not_delegated`. A lost response spends nothing: the same + * connection works on the next call. Test-only; not bundled. */ import { calendarFixture } from '../fixtures/google-calendar/scenario.mjs'; import type { @@ -34,8 +36,10 @@ export interface FakeStore extends PluginStore { readonly google: Fixture; /** The next PATCH reaches Google, then the relay throws (a lost response). */ loseNextWriteResponse(): void; - /** What the host would hold after the person connected again. */ + /** What the proxy would hold after the person connected again. */ reconnect(): void; + /** The delegation of `connectionId` revoked at the proxy, elsewhere. */ + revoke(connectionId: string): void; } export function fakeStore({ @@ -54,7 +58,7 @@ export function fakeStore({ let next = 0; let loseResponse = false; const connections = connected ? ['c1'] : []; - const spent = new Set(); + const revoked = new Set(); const wrap = ( subject: string, @@ -95,10 +99,17 @@ export function fakeStore({ calls.push(request); if (!connections.includes(request.connectionId)) throw new Error( - 'No google-calendar connection for this app. Connect again.', + `No google-calendar connection ${request.connectionId} is delegated to this app. Connect again.`, ); - if (spent.has(request.connectionId)) - throw new Error('Reconnect before retrying an uncertain request'); + if (revoked.has(request.connectionId)) + return { + status: 403, + headers: {}, + body: { + error: 'not_delegated', + message: 'the signing agent has no delegation for this connection', + }, + }; const url = new URL( `/proxy/${request.platform}${request.path}`, 'http://mock-proxy.test', @@ -118,7 +129,6 @@ export function fakeStore({ if (request.method === 'PATCH' && loseResponse) { loseResponse = false; - spent.add(request.connectionId); throw new Error('Failed to fetch'); } @@ -150,6 +160,9 @@ export function fakeStore({ reconnect: () => { connections.push(`c${connections.length + 1}`); }, + revoke: connectionId => { + revoked.add(connectionId); + }, getApp: async () => APP, getData: async () => ({ table: TABLE, rowClass: ROW_CLASS }), async getResource(subject) { diff --git a/integrations/calendar/app/relay.ts b/integrations/calendar/app/relay.ts index a25469b69..442f53521 100644 --- a/integrations/calendar/app/relay.ts +++ b/integrations/calendar/app/relay.ts @@ -1,19 +1,21 @@ // @wc-ignore-file /** * `adapter.ts` reads and writes through `Host.read(intent)` with absolute - * Google URLs. In the drive app that becomes one call to the host's proxy - * relay (`store.proxy.request`) per intent, for platform `google-calendar`. + * Google URLs. In the drive app that becomes one `store.proxy.request` per + * intent, for platform `google-calendar`: the host's frame client calls the + * integration proxy itself, with a capability the page signed and a key only + * it holds (ontola/atomic-plugins#54). The file keeps its old name, "relay". * - * The relay wants the provider path after `/proxy/google-calendar`. The - * integration-proxy strips its catalog server's base path (`/calendar/v3`) + * The proxy wants the provider path after `/proxy//google-calendar`. + * The integration-proxy strips its catalog server's base path (`/calendar/v3`) * itself, so the path keeps it: `/calendar/v3/calendars/{id}/events`. * Anything outside `https://www.googleapis.com/calendar/v3/` is refused here, * before it reaches the host. * * The adapter's `Authorization: secret:google-calendar` header is the * sandbox runtime's credential placeholder. It is dropped: the frame never - * names a credential, only a connection id. `If-Match` becomes the relay's - * `ifMatch` field; no other request header can cross the relay. + * names a credential, only a connection id. `If-Match` becomes the request's + * `ifMatch` field; no other request header crosses to the proxy. */ import type { ExternalIntent, @@ -25,10 +27,10 @@ export const PLATFORM = 'google-calendar'; export const UPSTREAM = 'https://www.googleapis.com/calendar/v3'; /** - * The relay call for a write threw instead of answering. The host may have - * sent it (the page spends its connection code before dispatch), so Google - * may or may not have applied it. Nothing about the event is assumed: the - * next preview reads what Google has. + * The call for a write threw instead of answering (a lost response, a + * timeout). It may have reached Google, so Google may or may not have + * applied it. Nothing about the event is assumed: the next preview reads + * what Google has. */ export class UncertainWriteError extends Error { constructor( @@ -43,6 +45,57 @@ export class UncertainWriteError extends Error { } } +/** + * The integration proxy's own refusals (`integration-proxy/src/api_error.rs`): + * `{ error, message }` with one of these codes, answered before the provider + * is called. The first group means the connection is gone or no longer this + * app's, so the person has to connect again. `unsupported_authorization` + * (a retired `Bearer` code) is left out: only a host from before #54 sends + * one. + */ +const RECONNECT_CODES = [ + 'unknown_connection', + 'not_delegated', + 'capability_scope', + 'platform_mismatch', + 'credential_refresh_failed', +]; +const REFUSAL_CODES = [ + ...RECONNECT_CODES, + 'missing_signature', + 'unsupported_signature_version', + 'invalid_agent', + 'agent_key_mismatch', + 'stale_timestamp', + 'bad_signature', + 'replayed', + 'invalid_capability', + 'capability_expired', + 'capability_too_long', + 'wrong_audience', + 'capability_key_mismatch', + 'not_owner', + 'access_denied', +]; + +/** A proxy refusal as an error, or `undefined` for a provider answer. */ +export function proxyRefusal(response: { + status: number; + body: unknown; +}): Error | undefined { + const body = response.body as { error?: unknown; message?: unknown } | null; + const code = typeof body?.error === 'string' ? body.error : undefined; + if (response.status < 400 || !code || !REFUSAL_CODES.includes(code)) + return undefined; + const detail = typeof body?.message === 'string' ? `: ${body.message}` : ''; + + return new Error( + RECONNECT_CODES.includes(code) + ? `The integration proxy refused this connection (${code}${detail}). Connect again.` + : `The integration proxy refused the request (${code}${detail}).`, + ); +} + export interface Relayed { /** The most recent relay response (for `retry-after` on a 429). */ last?: HostProxyResponse; @@ -99,6 +152,9 @@ export function relay(proxy: HostProxy, connectionId: string): Relayed { } out.last = response; + // Answered by the proxy itself, before Google: certainly not applied. + const refused = proxyRefusal(response); + if (refused) throw refused; return { status: response.status, diff --git a/integrations/calendar/app/store.ts b/integrations/calendar/app/store.ts index 6b068c9ee..8614a75fd 100644 --- a/integrations/calendar/app/store.ts +++ b/integrations/calendar/app/store.ts @@ -6,11 +6,16 @@ * sync with that file by hand; if they disagree, view-client.js is ground * truth. * - * A copy of `integrations/pets/app/store.ts` (the relay ops of - * atomic-server#1657, in the pinned `feat/plugin-debug`). Calendar is the - * first app to use `ifMatch`: view-client.js passes it through, and the - * page (`helpers/proxyConnections.ts`) sends it as `If-Match`. Kept per - * plugin on purpose (strict per-plugin containment). + * A copy of `integrations/pets/app/store.ts`. Calendar is the first app to + * use `ifMatch`: view-client.js sends it to the proxy as `If-Match`. Kept + * per plugin on purpose (strict per-plugin containment). + * + * `proxy` (ontola/atomic-plugins#54 phase 2): the frame names a platform and + * a connection id, never a credential. view-client.js makes an Ed25519 key in + * the frame's memory, gets a short-lived capability for it from the page + * (signed with the user's key, after the page checked the connection is + * delegated to this app), and calls the integration proxy directly, signing + * each request with that key. It is feature-detected, never assumed. */ export type JSONValue = @@ -37,13 +42,13 @@ export interface PluginResource { destroy(): Promise; } -/** One proxy call relayed by the host. Carries a connection reference, never a credential. */ +/** One proxy call, made by the host's frame client. Carries a connection reference, never a credential. */ export interface HostProxyRequest { platform: string; connectionId: string; - /** Provider path after the proxy's `/proxy/` prefix; may carry `?query`. */ + /** Provider path after the proxy's `/proxy//` prefix; may carry `?query`. */ path: string; - method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'; + method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; query?: Record; /** JSON text. */ body?: string; @@ -64,11 +69,22 @@ export interface ConnectionReference { platform: string; } +/** What `proxy.connect` resolves to, when it resolves. */ +export type ConnectResult = + | { status: 'cancelled' } + | { status: 'connected'; connectionId: string; platform: string }; + export interface HostProxy { request(request: HostProxyRequest): Promise; connections(args: { platform: string }): Promise; - /** Settles only when the person cancels; on consent the page navigates away. */ - connect(args: { platform: string }): Promise<{ status: 'cancelled' }>; + /** + * Shows the host's consent bar. Resolves `connected` when the person picks + * a connection they already have (the host delegates it to this app; no + * reload), `cancelled` when they cancel. Connecting a new account sends the + * page to the proxy and back, which reloads this view, so then it never + * settles. + */ + connect(args: { platform: string }): Promise; } export interface PluginStore { @@ -82,7 +98,7 @@ export interface PluginStore { propVals?: Record; }): Promise; subscribe(subject: string, handler: () => void): () => void; - /** Feature-detected: hosts without the relay (atomic-server#1624) lack it. */ + /** Feature-detected: hosts without integration-proxy support lack it. */ proxy?: HostProxy; } diff --git a/integrations/calendar/app/sync.test.ts b/integrations/calendar/app/sync.test.ts index 58cb82e6a..796cf91be 100644 --- a/integrations/calendar/app/sync.test.ts +++ b/integrations/calendar/app/sync.test.ts @@ -291,7 +291,7 @@ suite('Calendar drive app: supported path', () => { expect(store.google.writes).toEqual([]); }); - it('a lost write response is reported as unknown, stops the batch, and the next preview after reconnecting shows what Google has', async () => { + it('a lost write response is reported as unknown, stops the batch, and the next preview shows what Google has', async () => { const { store, controller } = await imported(); editRow(store, 'all-day', { [NAME]: 'All-day here' }); editRow(store, 'timed', { [NAME]: 'Timed here' }); @@ -309,7 +309,19 @@ suite('Calendar drive app: supported path', () => { // Google did apply the first; the second was never dispatched. expect(store.google.writes.map(w => w.id)).toEqual(['all-day']); - // The spent connection can't be used again; the app asks to reconnect. + // Nothing was spent (no connection codes since #54 phase 2): the same + // connection previews again straight away. + await controller.refresh(); + const after = ready(controller.state()); + // Google has the first change: it now agrees, nothing to send for it. + expect(after.summary.conflicts).toEqual([]); + expect(after.summary.review.map(r => r.edit.id)).toEqual(['timed']); + expect(store.calls.at(-1)!.connectionId).toBe('c1'); + }); + + it('a delegation revoked at the proxy asks to connect again', async () => { + const { store, controller } = await imported(); + store.revoke('c1'); await controller.refresh(); expect(controller.state()).toMatchObject({ kind: 'error', @@ -319,10 +331,7 @@ suite('Calendar drive app: supported path', () => { await ( await controller.load() ).refreshing; - const after = ready(controller.state()); - // Google has the first change: it now agrees, nothing to send for it. - expect(after.summary.conflicts).toEqual([]); - expect(after.summary.review.map(r => r.edit.id)).toEqual(['timed']); + ready(controller.state()); expect(store.calls.at(-1)!.connectionId).toBe('c2'); }); diff --git a/integrations/calendar/app/sync.ts b/integrations/calendar/app/sync.ts index 0cc6d3626..56efdce07 100644 --- a/integrations/calendar/app/sync.ts +++ b/integrations/calendar/app/sync.ts @@ -331,7 +331,7 @@ async function readRows( return out; } -/** The adapter's `Host` over the app's rows and the proxy relay. */ +/** The adapter's `Host` over the app's rows and the host's proxy calls. */ function host( proxy: HostProxy, connectionId: string, @@ -545,7 +545,7 @@ export type Outcome = | { status: 'sent'; title: string } /** Google answered 412: the event changed after the preview. */ | { status: 'stale'; title: string } - /** The relay threw: Google may or may not have the change. */ + /** The call threw: Google may or may not have the change. */ | { status: 'uncertain'; title: string; message: string } | { status: 'failed'; title: string; message: string } /** Not attempted, because an earlier write's outcome was unknown. */ @@ -554,10 +554,9 @@ export type Outcome = /** * Sends reviewed edits one by one, each a PATCH of only the changed fields, * with `If-Match` set to the ETag its preview read. A 412 or a refusal - * affects only that event. An uncertain outcome stops the batch: the host - * relay spends its connection code before dispatch, so after a lost - * response it cannot tell what happened either, and asks to reconnect. The - * baseline advances only for events Google confirmed. + * affects only that event. An uncertain outcome (the call threw, so it may + * have reached Google) stops the batch; the next preview reads what Google + * has. The baseline advances only for events Google confirmed. */ export async function send( store: PluginStore, diff --git a/integrations/issue-tracker/app/controller.ts b/integrations/issue-tracker/app/controller.ts index 9d0b3d080..7d7897eb0 100644 --- a/integrations/issue-tracker/app/controller.ts +++ b/integrations/issue-tracker/app/controller.ts @@ -63,8 +63,8 @@ export interface Controller { const RECONNECT = [ /^GitHub \S+ returned 401$/, - /connection for this app/, - /^Reconnect before retrying an uncertain request/, + /is delegated to this app/, + /^The integration proxy refused this connection/, ]; const PAUSED = [ /^Uncertain GitHub write/, @@ -240,8 +240,9 @@ export function createController( await session.state.flush(); } else if (current.kind !== 'not-connected') return current; set({ kind: 'connecting' }); - // Resolves only if the person cancels; on Connect the page navigates - // away and the view comes back fresh. + // Resolves when the person cancels or picks an existing connection; + // connecting a new account navigates away and the view comes back + // fresh. Either way, the connections decide what shows next. await store.proxy.connect({ platform: PLATFORM }); return this.load(); diff --git a/integrations/issue-tracker/app/fakeStore.ts b/integrations/issue-tracker/app/fakeStore.ts index 03880d266..df6a4d332 100644 --- a/integrations/issue-tracker/app/fakeStore.ts +++ b/integrations/issue-tracker/app/fakeStore.ts @@ -39,6 +39,8 @@ export interface FakeStore extends PluginStore { lostWriteLands?: boolean; /** Answers every relayed call with this status until cleared. */ status?: number; + /** Answers every call with this integration-proxy refusal code. */ + refusal?: string; lagReads: number; hideFromQuery: number; /** A person editing a row in the data-browser: no app write, no lag. */ @@ -127,6 +129,13 @@ export function fakeStore({ throw new Error(fake.fail); } + if (fake.refusal) + return { + status: fake.refusal === 'unknown_connection' ? 404 : 403, + headers: {}, + body: { error: fake.refusal, message: 'refused by the proxy' }, + }; + if (fake.status) return { status: fake.status, diff --git a/integrations/issue-tracker/app/store.ts b/integrations/issue-tracker/app/store.ts index c8c154bf3..1dcadc986 100644 --- a/integrations/issue-tracker/app/store.ts +++ b/integrations/issue-tracker/app/store.ts @@ -7,11 +7,13 @@ * import them from yet, and sharing one copy is a maintainer decision * (per-plugin containment). If they disagree, view-client.js is ground truth. * - * `proxy` is the generic host relay the pets work (#52) adds to - * atomic-server. It is feature-detected, never assumed: without it the app - * says so and fetches nothing. Its contract is in that plan: the frame names - * a platform and a connection id, never a credential; the rotating code stays - * in the parent page. + * `proxy` (ontola/atomic-plugins#54 phase 2): the frame names a platform and + * a connection id, never a credential. view-client.js makes an Ed25519 key in + * the frame's memory, gets a short-lived capability for it from the page + * (signed with the user's key, after the page checked the connection is + * delegated to this app), and calls the integration proxy directly, signing + * each request with that key. It is feature-detected, never assumed. Without it + * the app says so and fetches nothing. */ export type JSONValue = @@ -38,13 +40,13 @@ export interface PluginResource { destroy(): Promise; } -/** One provider call, relayed by the host. A connection reference, never a credential. */ +/** One proxy call, made by the host's frame client. Carries a connection reference, never a credential. */ export interface HostProxyRequest { platform: string; connectionId: string; - /** The provider path after the proxy's `/proxy/`, e.g. `/v1/search`. */ + /** The provider path after the proxy's `/proxy//`, e.g. `/v1/search`. */ path: string; - method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'; + method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; query?: Record; /** JSON text. */ body?: string; @@ -58,14 +60,25 @@ export interface HostProxyResponse { body: unknown; } +/** What `proxy.connect` resolves to, when it resolves. */ +export type ConnectResult = + | { status: 'cancelled' } + | { status: 'connected'; connectionId: string; platform: string }; + export interface HostProxy { request(request: HostProxyRequest): Promise; - /** Connections this app made for `platform`, in this browser. */ + /** Connections for `platform` the person delegated to this app, at the proxy. */ connections(args: { platform: string; }): Promise<{ connectionId: string; platform: string }[]>; - /** Asks the host to show its consent bar; on Connect the page navigates away. */ - connect(args: { platform: string }): Promise<{ status: 'cancelled' }>; + /** + * Shows the host's consent bar. Resolves `connected` when the person picks + * a connection they already have (the host delegates it to this app; no + * reload), `cancelled` when they cancel. Connecting a new account sends the + * page to the proxy and back, which reloads this view, so then it never + * settles. + */ + connect(args: { platform: string }): Promise; } export interface PluginStore { diff --git a/integrations/issue-tracker/app/sync.test.ts b/integrations/issue-tracker/app/sync.test.ts index bffcde549..fc28e23bc 100644 --- a/integrations/issue-tracker/app/sync.test.ts +++ b/integrations/issue-tracker/app/sync.test.ts @@ -284,7 +284,8 @@ group('GitHub issues drive app', () => { const [issue] = rows(store).find(([, p]) => p[number] === 1)!; store.edit(issue, { [NAME]: 'Renamed' }); await controller.sync(); - store.fail = 'No github-issues connection for this app. Connect again.'; + store.fail = + 'No github-issues connection c1 is delegated to this app. Connect again.'; const refused = ready(await controller.send()); expect(refused.problem?.kind).toBe('reconnect'); @@ -451,12 +452,31 @@ group('frame store adapter', () => { ).rejects.toMatchObject({ notSent: true, }); - store.fail = 'Reconnect before retrying an uncertain request'; + store.fail = + 'This browser cannot make an Ed25519 key (WebCrypto Ed25519 is missing)'; await expect( dispatch('/repos/a/b/issues', { method: 'GET' }), ).rejects.toMatchObject({ notSent: true, }); + store.fail = undefined; + // The proxy's own refusal comes back as a response, not a throw: it + // never reached GitHub, and a lost delegation means connect again. + store.refusal = 'not_delegated'; + await expect( + dispatch('/repos/a/b/issues', { method: 'POST', body: '{}' }), + ).rejects.toMatchObject({ + notSent: true, + message: expect.stringMatching(/not_delegated.*Connect again\.$/), + }); + store.refusal = 'stale_timestamp'; + await expect( + dispatch('/repos/a/b/issues', { method: 'GET' }), + ).rejects.toMatchObject({ + notSent: true, + message: expect.not.stringMatching(/Connect again/), + }); + store.refusal = undefined; store.fail = 'The host did not answer proxy in time.'; await expect( dispatch('/repos/a/b/issues', { method: 'GET' }), diff --git a/integrations/issue-tracker/app/transport.ts b/integrations/issue-tracker/app/transport.ts index d91ed58ac..633c8aa74 100644 --- a/integrations/issue-tracker/app/transport.ts +++ b/integrations/issue-tracker/app/transport.ts @@ -17,28 +17,87 @@ export type Dispatch = ( ) => Promise; /** - * Host errors that are raised before the relay spends a connection code, so - * the request certainly never left this browser (atomic-server - * `helpers/proxyConnections.ts` and `chunks/AppPage/hostStore.ts` at the - * pin). Matching on text is brittle; a message that stops matching only makes - * a write look uncertain, which pauses sync instead of resending it. + * Host errors raised before the frame sends anything to the proxy, so the + * request certainly never left this browser: the page refusing to mint a + * capability, the frame unable to make its key, or an invalid request + * (atomic-server `helpers/proxyConnections.ts`, `chunks/AppPage/hostStore.ts` + * and `view-client.js` at the pin). Matching on text is brittle; a message + * that stops matching only makes a write look uncertain, which pauses sync + * instead of resending it. */ const NOT_SENT = [ - /^No [a-z0-9-]+ connection for this app/, - /^Reconnect before retrying an uncertain request/, + /^No [a-z0-9-]+ connection .* is delegated to this app/, /^This host cannot reach the integration proxy/, - /^This browser needs Web Locks/, + /^This browser (has no WebCrypto|cannot make an Ed25519 key)/, + /^The host returned no capability/, + /^This app has no identity of its own yet/, + /^The integration proxy refused (GET|POST|DELETE) \/connections/, /^Invalid (platform|proxy path|proxy method|proxy query|If-Match)/, /^A (GET )?proxy request/, - /^connectionId is required/, + /^(connectionId|publicKey|platform) is required/, /^Sign in/, ]; /** - * `proxyTransport`'s `dispatch` over the host's relay (`store.proxy.request`). - * The frame names the connection; the host page holds and rotates its code, - * serialises calls per connection and returns status and body only. This - * module never sees or stores a credential. + * The integration proxy's own refusals (`integration-proxy/src/api_error.rs`): + * `{ error, message }` with one of these codes. The proxy answers them before + * calling GitHub, so a refused write was not sent. The first group means the + * connection is gone or no longer this app's: connect again. + * `unsupported_authorization` (a retired `Bearer` code) is left out: only a + * host from before #54 sends one. + */ +const RECONNECT_CODES = [ + 'unknown_connection', + 'not_delegated', + 'capability_scope', + 'platform_mismatch', + 'credential_refresh_failed', +]; +const REFUSAL_CODES = [ + ...RECONNECT_CODES, + 'missing_signature', + 'unsupported_signature_version', + 'invalid_agent', + 'agent_key_mismatch', + 'stale_timestamp', + 'bad_signature', + 'replayed', + 'invalid_capability', + 'capability_expired', + 'capability_too_long', + 'wrong_audience', + 'capability_key_mismatch', + 'not_owner', + 'access_denied', +]; + +/** A proxy refusal as an error, or `undefined` for a provider answer. */ +export function proxyRefusal(response: { + status: number; + body: unknown; +}): (Error & { notSent: true }) | undefined { + const body = response.body as { error?: unknown; message?: unknown } | null; + const code = typeof body?.error === 'string' ? body.error : undefined; + if (response.status < 400 || !code || !REFUSAL_CODES.includes(code)) + return undefined; + const detail = typeof body?.message === 'string' ? `: ${body.message}` : ''; + + return Object.assign( + new Error( + RECONNECT_CODES.includes(code) + ? `The integration proxy refused this connection (${code}${detail}). Connect again.` + : `The integration proxy refused the request (${code}${detail}).`, + ), + { notSent: true as const }, + ); +} + +/** + * `proxyTransport`'s `dispatch` over the host's `store.proxy.request`. The + * frame names the connection; the host's frame client calls the proxy with a + * capability the page signed and a key it holds itself, and returns status, + * a few headers and the body. This module never sees or stores a + * credential. * * `path` comes from the GitHub adapter as `/repos/{owner}/{name}/issues…` * with its query string; it is split into the relay's `path` and `query`, @@ -82,6 +141,9 @@ export function relayDispatch( }); } + const refused = proxyRefusal(response); + if (refused) throw refused; + return { status: response.status, body: diff --git a/integrations/notion/app/controller.ts b/integrations/notion/app/controller.ts index ce478738a..6eb83fe4c 100644 --- a/integrations/notion/app/controller.ts +++ b/integrations/notion/app/controller.ts @@ -71,11 +71,13 @@ export function createController( async connect() { if (current.kind !== 'not-connected' || !store.proxy) return current; set({ kind: 'connecting' }); - // Resolves only if the user cancels; on Connect the page navigates - // away and comes back to a fresh view. - await store.proxy.connect({ platform: PLATFORM }); + // Connecting a new account navigates away and comes back to a fresh + // view; picking an existing one resolves `connected`, with no reload. + const result = await store.proxy.connect({ platform: PLATFORM }); - return set({ kind: 'not-connected' }); + return result?.status === 'connected' + ? this.load() + : set({ kind: 'not-connected' }); }, async sync() { diff --git a/integrations/notion/app/store.ts b/integrations/notion/app/store.ts index 8f9a89a29..fa9b433c5 100644 --- a/integrations/notion/app/store.ts +++ b/integrations/notion/app/store.ts @@ -6,11 +6,13 @@ * timesheets'/pets' copies; there is no package to import them from yet. If * they disagree, view-client.js is ground truth. * - * `proxy` is the generic host relay the pets work (#52) adds to - * atomic-server. It is feature-detected, never assumed: without it the app - * says so and fetches nothing. Its contract is in that plan: the frame names - * a platform and a connection id, never a credential; the rotating code stays - * in the parent page. + * `proxy` (ontola/atomic-plugins#54 phase 2): the frame names a platform and + * a connection id, never a credential. view-client.js makes an Ed25519 key in + * the frame's memory, gets a short-lived capability for it from the page + * (signed with the user's key, after the page checked the connection is + * delegated to this app), and calls the integration proxy directly, signing + * each request with that key. It is feature-detected, never assumed. Without it + * the app says so and fetches nothing. */ export type JSONValue = @@ -37,13 +39,13 @@ export interface PluginResource { destroy(): Promise; } -/** One provider call, relayed by the host. A connection reference, never a credential. */ +/** One proxy call, made by the host's frame client. Carries a connection reference, never a credential. */ export interface HostProxyRequest { platform: string; connectionId: string; - /** The provider path after the proxy's `/proxy/`, e.g. `/v1/search`. */ + /** The provider path after the proxy's `/proxy//`, e.g. `/v1/search`. */ path: string; - method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'; + method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; query?: Record; /** JSON text. */ body?: string; @@ -57,14 +59,25 @@ export interface HostProxyResponse { body: unknown; } +/** What `proxy.connect` resolves to, when it resolves. */ +export type ConnectResult = + | { status: 'cancelled' } + | { status: 'connected'; connectionId: string; platform: string }; + export interface HostProxy { request(request: HostProxyRequest): Promise; - /** Connections this app made for `platform`, in this browser. */ + /** Connections for `platform` the person delegated to this app, at the proxy. */ connections(args: { platform: string; }): Promise<{ connectionId: string; platform: string }[]>; - /** Asks the host to show its consent bar; on Connect the page navigates away. */ - connect(args: { platform: string }): Promise<{ status: 'cancelled' }>; + /** + * Shows the host's consent bar. Resolves `connected` when the person picks + * a connection they already have (the host delegates it to this app; no + * reload), `cancelled` when they cancel. Connecting a new account sends the + * page to the proxy and back, which reloads this view, so then it never + * settles. + */ + connect(args: { platform: string }): Promise; } export interface PluginStore { diff --git a/integrations/notion/app/transport.ts b/integrations/notion/app/transport.ts index 027e0e59c..6a2728b09 100644 --- a/integrations/notion/app/transport.ts +++ b/integrations/notion/app/transport.ts @@ -5,15 +5,68 @@ import type { HostProxy } from './store.js'; export const PLATFORM = 'notion'; /** - * syncables' injected transport, over the host's proxy relay. syncables - * builds absolute URLs under the document's server - * (`https://api.notion.com/v1`). The relay wants the provider path after - * `/proxy/notion`, which keeps the `/v1` base path (integration-proxy only - * allows `/v1/search`, not `/search`). Anything outside that server is refused - * before it reaches the host. + * The integration proxy's own refusals (`integration-proxy/src/api_error.rs`): + * `{ error, message }` with one of these codes, answered before the provider + * is called. The first group means the connection is gone or no longer this + * app's, so the person has to connect again. `unsupported_authorization` + * (a retired `Bearer` code) is left out: only a host from before #54 sends + * one. + */ +const RECONNECT_CODES = [ + 'unknown_connection', + 'not_delegated', + 'capability_scope', + 'platform_mismatch', + 'credential_refresh_failed', +]; +const REFUSAL_CODES = [ + ...RECONNECT_CODES, + 'missing_signature', + 'unsupported_signature_version', + 'invalid_agent', + 'agent_key_mismatch', + 'stale_timestamp', + 'bad_signature', + 'replayed', + 'invalid_capability', + 'capability_expired', + 'capability_too_long', + 'wrong_audience', + 'capability_key_mismatch', + 'not_owner', + 'access_denied', +]; + +/** A proxy refusal as an error, or `undefined` for a provider answer. */ +export function proxyRefusal(response: { + status: number; + body: unknown; +}): Error | undefined { + const body = response.body as { error?: unknown; message?: unknown } | null; + const code = typeof body?.error === 'string' ? body.error : undefined; + if (response.status < 400 || !code || !REFUSAL_CODES.includes(code)) + return undefined; + const detail = typeof body?.message === 'string' ? `: ${body.message}` : ''; + + return new Error( + RECONNECT_CODES.includes(code) + ? `The integration proxy refused this connection (${code}${detail}). Connect again.` + : `The integration proxy refused the request (${code}${detail}).`, + ); +} + +/** + * syncables' injected transport, over the host's `store.proxy.request` (the + * host's frame client calls the proxy itself with a capability and its own + * key, ontola/atomic-plugins#54). syncables builds absolute URLs under the + * document's server (`https://api.notion.com/v1`). The proxy wants the + * provider path after `/proxy//notion`, which keeps the `/v1` + * base path (integration-proxy only allows `/v1/search`, not `/search`). + * Anything outside that server is refused before it reaches the host. * - * The relay parses a JSON response body; syncables wants text, so it is + * The host parses a JSON response body; syncables wants text, so it is * serialised again. Notion's list bodies are small, capped at 100 results. + * A proxy refusal is thrown rather than handed over as Notion's answer. */ export function syncablesTransport( proxy: HostProxy, @@ -41,6 +94,9 @@ export function syncablesTransport( ...(request.body === undefined ? {} : { body: request.body }), }); + const refused = proxyRefusal(response); + if (refused) throw refused; + return { status: response.status, headers: response.headers ?? {}, diff --git a/integrations/pets/app/controller.ts b/integrations/pets/app/controller.ts index 23cc638c8..37e57aaf5 100644 --- a/integrations/pets/app/controller.ts +++ b/integrations/pets/app/controller.ts @@ -100,10 +100,11 @@ export function createController( set({ kind: 'connecting' }); try { - // On consent the host navigates away and this view reloads; the - // promise only settles when the person cancels. - await proxy.connect({ platform: PLATFORM }); - set({ kind: 'disconnected' }); + // Connecting a new account navigates away and reloads this view; + // picking an existing one resolves `connected`, with no reload. + const result = await proxy.connect({ platform: PLATFORM }); + if (result?.status === 'connected') await this.load(); + else set({ kind: 'disconnected' }); } catch (error) { set({ kind: 'error', message: message(error) }); } diff --git a/integrations/pets/app/store.ts b/integrations/pets/app/store.ts index ad3a33503..29b6751d9 100644 --- a/integrations/pets/app/store.ts +++ b/integrations/pets/app/store.ts @@ -6,11 +6,17 @@ * sync with that file by hand; if they disagree, view-client.js is ground * truth. * - * A copy of `integrations/timesheets/app/store.ts`, extended with the relay - * ops atomic-server#1657 adds (merged into `feat/plugin-debug`) - * (`connections`, `connect`, response `headers`, request `method`/`body`). + * A copy of `integrations/timesheets/app/store.ts`, extended with + * `connections`, `connect`, response `headers` and request `method`/`body`. * Kept per plugin on purpose (strict per-plugin containment); sharing one * copy is a maintainer decision, see README.md. + * + * `proxy` (ontola/atomic-plugins#54 phase 2): the frame names a platform and + * a connection id, never a credential. view-client.js makes an Ed25519 key in + * the frame's memory, gets a short-lived capability for it from the page + * (signed with the user's key, after the page checked the connection is + * delegated to this app), and calls the integration proxy directly, signing + * each request with that key. It is feature-detected, never assumed. */ export type JSONValue = @@ -37,13 +43,13 @@ export interface PluginResource { destroy(): Promise; } -/** One proxy call relayed by the host. Carries a connection reference, never a credential. */ +/** One proxy call, made by the host's frame client. Carries a connection reference, never a credential. */ export interface HostProxyRequest { platform: string; connectionId: string; - /** Provider path after the proxy's `/proxy/` prefix; may carry `?query`. */ + /** Provider path after the proxy's `/proxy//` prefix; may carry `?query`. */ path: string; - method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'; + method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; query?: Record; /** JSON text. */ body?: string; @@ -63,11 +69,22 @@ export interface ConnectionReference { platform: string; } +/** What `proxy.connect` resolves to, when it resolves. */ +export type ConnectResult = + | { status: 'cancelled' } + | { status: 'connected'; connectionId: string; platform: string }; + export interface HostProxy { request(request: HostProxyRequest): Promise; connections(args: { platform: string }): Promise; - /** Settles only when the person cancels; on consent the page navigates away. */ - connect(args: { platform: string }): Promise<{ status: 'cancelled' }>; + /** + * Shows the host's consent bar. Resolves `connected` when the person picks + * a connection they already have (the host delegates it to this app; no + * reload), `cancelled` when they cancel. Connecting a new account sends the + * page to the proxy and back, which reloads this view, so then it never + * settles. + */ + connect(args: { platform: string }): Promise; } export interface PluginStore { @@ -81,7 +98,7 @@ export interface PluginStore { propVals?: Record; }): Promise; subscribe(subject: string, handler: () => void): () => void; - /** Feature-detected: hosts without the relay (atomic-server#1624) lack it. */ + /** Feature-detected: hosts without integration-proxy support lack it. */ proxy?: HostProxy; } diff --git a/integrations/pets/app/sync.test.ts b/integrations/pets/app/sync.test.ts index 9ab03c168..c951d195c 100644 --- a/integrations/pets/app/sync.test.ts +++ b/integrations/pets/app/sync.test.ts @@ -114,6 +114,33 @@ describePlatform('relayTransport', () => { }); expect(store.calls.at(-1)!.path).toBe('/pets?page=2'); }); + + it("throws the integration proxy's own refusals instead of passing them on as Pets' answer", async () => { + const answer = (status: number, body: unknown) => + relayTransport( + { + request: async () => ({ status, headers: {}, body }), + connections: async () => [], + connect: async () => ({ status: 'cancelled' as const }), + }, + { platform: 'pets', connectionId: 'c1' }, + 'https://pets.example/v1', + )({ + url: new URL('https://pets.example/v1/pets'), + method: 'GET', + headers: {}, + }); + await expect( + answer(403, { error: 'not_delegated', message: 'no delegation' }), + ).rejects.toThrow( + 'The integration proxy refused this connection (not_delegated: no delegation). Connect again.', + ); + await expect(answer(401, { error: 'stale_timestamp' })).rejects.toThrow( + 'The integration proxy refused the request (stale_timestamp).', + ); + // A provider's own error body is Pets' answer, passed on as is. + expect((await answer(404, { error: 'Not found' })).status).toBe(404); + }); }); describePlatform('controller', () => { diff --git a/integrations/pets/app/transport.ts b/integrations/pets/app/transport.ts index 7db20aac1..1cd3d21c5 100644 --- a/integrations/pets/app/transport.ts +++ b/integrations/pets/app/transport.ts @@ -7,11 +7,65 @@ import type { import type { HostProxy } from './store.js'; /** - * A syncables `Transport` that goes through the host's proxy relay. + * The integration proxy's own refusals (`integration-proxy/src/api_error.rs`): + * `{ error, message }` with one of these codes, answered before the provider + * is called. The first group means the connection is gone or no longer this + * app's, so the person has to connect again. `unsupported_authorization` + * (a retired `Bearer` code) is left out: only a host from before #54 sends + * one. + */ +const RECONNECT_CODES = [ + 'unknown_connection', + 'not_delegated', + 'capability_scope', + 'platform_mismatch', + 'credential_refresh_failed', +]; +const REFUSAL_CODES = [ + ...RECONNECT_CODES, + 'missing_signature', + 'unsupported_signature_version', + 'invalid_agent', + 'agent_key_mismatch', + 'stale_timestamp', + 'bad_signature', + 'replayed', + 'invalid_capability', + 'capability_expired', + 'capability_too_long', + 'wrong_audience', + 'capability_key_mismatch', + 'not_owner', + 'access_denied', +]; + +/** A proxy refusal as an error, or `undefined` for a provider answer. */ +export function proxyRefusal(response: { + status: number; + body: unknown; +}): Error | undefined { + const body = response.body as { error?: unknown; message?: unknown } | null; + const code = typeof body?.error === 'string' ? body.error : undefined; + if (response.status < 400 || !code || !REFUSAL_CODES.includes(code)) + return undefined; + const detail = typeof body?.message === 'string' ? `: ${body.message}` : ''; + + return new Error( + RECONNECT_CODES.includes(code) + ? `The integration proxy refused this connection (${code}${detail}). Connect again.` + : `The integration proxy refused the request (${code}${detail}).`, + ); +} + +/** + * A syncables `Transport` over the host's `store.proxy.request`: the host's + * frame client calls the integration proxy with a capability the page signed + * and a key only it holds (ontola/atomic-plugins#54). A proxy refusal is + * thrown, not handed to syncables as if Pets had answered. * * syncables builds absolute upstream URLs under the document's * `servers[0].url` (and follows `Link: rel="next"` URLs the provider sends). - * The proxy wants the provider path after `/proxy/`, so the + * The proxy wants the provider path after `/proxy//`, so the * upstream base is stripped. Anything outside that base is refused here, * before it reaches the host: a provider-sent link must not be able to steer * the connection somewhere else. @@ -43,6 +97,9 @@ export function relayTransport( ...(request.body !== undefined ? { body: request.body } : {}), }); + const refused = proxyRefusal(response); + if (refused) throw refused; + return { status: response.status, headers: response.headers ?? {}, diff --git a/integrations/timesheets/app/controller.ts b/integrations/timesheets/app/controller.ts index 697f47482..2c8f0fab8 100644 --- a/integrations/timesheets/app/controller.ts +++ b/integrations/timesheets/app/controller.ts @@ -165,9 +165,15 @@ export function createController( set({ kind: 'connecting' }); try { - // On consent the host navigates away and this view reloads; the - // promise only settles when the person cancels. - await store.proxy.connect({ platform: PLATFORM }); + // Connecting a new account navigates away and reloads this view; + // picking an existing one resolves `connected`, with no reload. + const result = await store.proxy.connect({ platform: PLATFORM }); + + if (result?.status === 'connected') { + await controller.load(); + + return current; + } return set({ kind: 'not-connected' }); } catch (error) { diff --git a/integrations/timesheets/app/store.ts b/integrations/timesheets/app/store.ts index b0e248f01..d6fe4bf5b 100644 --- a/integrations/timesheets/app/store.ts +++ b/integrations/timesheets/app/store.ts @@ -16,8 +16,11 @@ * removed with `remove()`; the host writes the removals as an `/app-write` * `remove` and then sets the rest (atomic-server#1690). Afterwards the * host re-reads the resource, so the next `get` sees the write. - * - `proxy` is the relay from atomic-server#1657 (for #1624): `request`, - * `connections` and `connect`. Feature-detected, never assumed. + * - `proxy`: `request`, `connections` and `connect`. Since + * ontola/atomic-plugins#54 phase 2 view-client.js calls the integration + * proxy itself, with a capability from the page and a key only the frame + * holds; the frame names a connection id, never a credential. + * Feature-detected, never assumed. */ export type JSONValue = @@ -44,13 +47,13 @@ export interface PluginResource { destroy(): Promise; } -/** One proxy call relayed by the host. Carries a connection reference, never a credential. */ +/** One proxy call, made by the host's frame client. Carries a connection reference, never a credential. */ export interface HostProxyRequest { platform: string; connectionId: string; - /** Provider path after the proxy's `/proxy/` prefix. */ + /** Provider path after the proxy's `/proxy//` prefix. */ path: string; - method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'; + method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; query?: Record; /** JSON text. */ body?: string; @@ -64,18 +67,29 @@ export interface HostProxyResponse { body: unknown; } -/** A connection held by the host page, named by public ids only. */ +/** A connection at the proxy, named by public ids only. */ export interface ConnectionReference { platform: string; connectionId: string; } +/** What `proxy.connect` resolves to, when it resolves. */ +export type ConnectResult = + | { status: 'cancelled' } + | { status: 'connected'; connectionId: string; platform: string }; + export interface HostProxy { request(request: HostProxyRequest): Promise; - /** This app's connections for `platform`, in this browser. */ + /** Connections for `platform` the person delegated to this app, at the proxy. */ connections(args: { platform: string }): Promise; - /** Shows the host's consent bar; settles only when the person cancels. */ - connect(args: { platform: string }): Promise<{ status: 'cancelled' }>; + /** + * Shows the host's consent bar. Resolves `connected` when the person picks + * a connection they already have (the host delegates it to this app; no + * reload), `cancelled` when they cancel. Connecting a new account sends the + * page to the proxy and back, which reloads this view, so then it never + * settles. + */ + connect(args: { platform: string }): Promise; } export interface PluginStore { @@ -90,7 +104,7 @@ export interface PluginStore { }): Promise; /** `handler` takes no argument; re-fetch via getResource for the new data. */ subscribe(subject: string, handler: () => void): () => void; - /** Feature-detected: hosts without the relay (atomic-server#1624) lack it. */ + /** Feature-detected: hosts without integration-proxy support lack it. */ proxy?: HostProxy; } diff --git a/integrations/timesheets/app/sync.test.ts b/integrations/timesheets/app/sync.test.ts index 5daeb6cbd..2855932f9 100644 --- a/integrations/timesheets/app/sync.test.ts +++ b/integrations/timesheets/app/sync.test.ts @@ -280,3 +280,23 @@ describe('syncClockify against the shared Clockify mock', () => { expect(result.created).toBe(53); }); }); + +describe('relayTransport and the integration proxy', () => { + it("throws the proxy's own refusal instead of reading it as Clockify's answer", async () => { + const transport = relayTransport( + { + request: async () => ({ + status: 404, + headers: {}, + body: { error: 'unknown_connection', message: 'no such connection' }, + }), + connections: async () => [], + connect: async () => ({ status: 'cancelled' as const }), + }, + CONNECTION, + ); + await expect(transport.request('/v1/user')).rejects.toThrow( + 'The integration proxy refused this connection (unknown_connection: no such connection). Connect again.', + ); + }); +}); diff --git a/integrations/timesheets/app/transport.ts b/integrations/timesheets/app/transport.ts index 6d9374522..0e44838e2 100644 --- a/integrations/timesheets/app/transport.ts +++ b/integrations/timesheets/app/transport.ts @@ -8,10 +8,11 @@ export const PLATFORM = 'clockify'; * only ever sees this interface, so it cannot hold, rotate or persist a * credential; whoever implements it owns authority. * - * The one implementation is the host relay (`relayTransport`): the parent - * page performs the call with the connection it holds and returns only - * `{ status, headers, body }`. A signed capability (#40) would be a second - * implementation; it is not built. + * The one implementation is `relayTransport`, over the host's + * `store.proxy.request`: since ontola/atomic-plugins#54 phase 2 the host's + * frame client calls the proxy itself, with a capability the page signed and + * a key only it holds, and returns `{ status, headers, body }`. A proxy + * refusal (`proxyRefusal`) is thrown rather than read as Clockify's answer. */ export interface ProxyTransport { request( @@ -47,22 +48,78 @@ export async function requestJson( } /** - * The host-relayed transport for one connection. There is intentionally no - * frame-side fallback that takes a rotating code: the frame is null-origin, - * has no storage, and a resource must not carry a credential (#21). + * The integration proxy's own refusals (`integration-proxy/src/api_error.rs`): + * `{ error, message }` with one of these codes, answered before the provider + * is called. The first group means the connection is gone or no longer this + * app's, so the person has to connect again. `unsupported_authorization` + * (a retired `Bearer` code) is left out: only a host from before #54 sends + * one. + */ +const RECONNECT_CODES = [ + 'unknown_connection', + 'not_delegated', + 'capability_scope', + 'platform_mismatch', + 'credential_refresh_failed', +]; +const REFUSAL_CODES = [ + ...RECONNECT_CODES, + 'missing_signature', + 'unsupported_signature_version', + 'invalid_agent', + 'agent_key_mismatch', + 'stale_timestamp', + 'bad_signature', + 'replayed', + 'invalid_capability', + 'capability_expired', + 'capability_too_long', + 'wrong_audience', + 'capability_key_mismatch', + 'not_owner', + 'access_denied', +]; + +/** A proxy refusal as an error, or `undefined` for a provider answer. */ +export function proxyRefusal(response: { + status: number; + body: unknown; +}): Error | undefined { + const body = response.body as { error?: unknown; message?: unknown } | null; + const code = typeof body?.error === 'string' ? body.error : undefined; + if (response.status < 400 || !code || !REFUSAL_CODES.includes(code)) + return undefined; + const detail = typeof body?.message === 'string' ? `: ${body.message}` : ''; + + return new Error( + RECONNECT_CODES.includes(code) + ? `The integration proxy refused this connection (${code}${detail}). Connect again.` + : `The integration proxy refused the request (${code}${detail}).`, + ); +} + +/** + * The transport for one connection, over the host. There is intentionally no + * frame-side credential of any kind: the frame is null-origin, has no + * storage, and a resource must not carry a credential (#21). */ export function relayTransport( proxy: HostProxy, connection: ConnectionReference, ): ProxyTransport { return { - request: (path, query) => - proxy.request({ + async request(path, query) { + const response = await proxy.request({ platform: connection.platform, connectionId: connection.connectionId, path, method: 'GET', ...(query ? { query } : {}), - }), + }); + const refused = proxyRefusal(response); + if (refused) throw refused; + + return response; + }, }; } From 765b0f6b0c3c3dcd053ffd52060efb4b26be7f26 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 24 Sep 2026 17:05:49 +0200 Subject: [PATCH 4/8] Pin atomic-server to claude/atomic-plugins-pin-phase2 11264e83e (#54 phase 2) Descends from the previous pin 8270cdf6a and adds ontola/atomic-server #1696 (v2 request signatures), #1702 (host-signed ctx.http to the configured proxy), #1710 (installation app ids, runtimes, delegated connections), #1725 (proxy: [...] and atomic-proxy: URLs) and #1697 (frame capabilities replace the proxy relay). Co-Authored-By: Claude Opus 5.5 --- .atomic-server-ref | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.atomic-server-ref b/.atomic-server-ref index 5b1165c0a..53b872e1f 100644 --- a/.atomic-server-ref +++ b/.atomic-server-ref @@ -1 +1 @@ -8270cdf6a4d9e9c44dfab2e1f33b76bdcca3a2d7 +11264e83e18ca59e0e0bd696eef6c8ac7ced5f68 From 0ce15b058be347b2a59959deec612e91942ff70c Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 24 Sep 2026 17:09:25 +0200 Subject: [PATCH 5/8] pets: release 0.1.1 of the drive app for the #54 phase 2 host apps/pets/0.1.1/ui.js is app/build.mjs's output after the phase 2 app changes (connect may resolve `connected`; proxy refusals are thrown). 0.1.0 stays as published; the catalog now pins 0.1.1 and its integrity. Co-Authored-By: Claude Opus 5.5 --- apps/pets/0.1.1/ui.js | 1426 ++++++++++++++++++++++++++++++++ integrations/catalog.json | 6 +- integrations/pets/package.json | 2 +- 3 files changed, 1430 insertions(+), 4 deletions(-) create mode 100644 apps/pets/0.1.1/ui.js diff --git a/apps/pets/0.1.1/ui.js b/apps/pets/0.1.1/ui.js new file mode 100644 index 000000000..636ecfb31 --- /dev/null +++ b/apps/pets/0.1.1/ui.js @@ -0,0 +1,1426 @@ +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/openapi/resolve-refs.js +function resolveRefs(document) { + const root = document; + const resolving = /* @__PURE__ */ new Set(); + const resolved2 = /* @__PURE__ */ new Map(); + function resolvePointer(ref) { + const segments = ref.replace(/^#\//, "").split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~")); + let node = root; + for (const segment of segments) { + node = node[segment]; + } + return node; + } + function walk(node) { + if (Array.isArray(node)) { + return node.map(walk); + } + if (node && typeof node === "object") { + const obj = node; + const ref = obj["$ref"]; + if (typeof ref === "string") { + if (!ref.startsWith("#/")) { + return obj; + } + const target = resolvePointer(ref); + if (!target || typeof target !== "object") { + return target; + } + if (resolved2.has(target)) { + return resolved2.get(target); + } + if (resolving.has(target)) { + return target; + } + resolving.add(target); + const result2 = walk(target); + resolving.delete(target); + resolved2.set(target, result2); + return result2; + } + const result = {}; + for (const [key, value] of Object.entries(obj)) { + result[key] = walk(value); + } + return result; + } + return node; + } + return walk(root); +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/read/model.js +function isRecord(value) { + return typeof value === "object" && value !== null && !Array.isArray(value); +} +function asText(value) { + return typeof value === "string" ? value : value === null || value === void 0 ? "" : JSON.stringify(value); +} +function pathVariables(template) { + return [...template.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]); +} +function crudResourcesOf(document) { + const raw = document.components?.["crudResources"]; + if (!isRecord(raw)) { + throw new Error("OpenAPI document declares no crudResources; apply the CRUD-causality overlay"); + } + return raw; +} +function listMethodOf(collection) { + const raw = collection["x-list-method"]; + if (raw === void 0) { + return "GET"; + } + const method = typeof raw === "string" ? raw.toUpperCase() : ""; + if (method !== "GET" && method !== "POST") { + throw new Error(`Unsupported x-list-method ${asText(raw)}`); + } + return method; +} +function discoverReadModel(document) { + const collections = []; + const firstCollection = /* @__PURE__ */ new Map(); + const bindings = []; + for (const [resource, def] of Object.entries(crudResourcesOf(document))) { + if (!isRecord(def)) { + continue; + } + const identity = isRecord(def["identity"]) ? def["identity"] : {}; + const itemUrl = typeof identity["urlTemplate"] === "string" ? identity["urlTemplate"] : ""; + const cols = isRecord(def["collections"]) ? def["collections"] : {}; + const collectionUrlHas = (param) => Object.values(cols).some((c) => isRecord(c) && typeof c["urlTemplate"] === "string" && c["urlTemplate"].includes(`{${param}}`)); + let idField = "id"; + const identityBindings = isRecord(identity["bindings"]) ? identity["bindings"] : {}; + for (const [param, binding] of Object.entries(identityBindings)) { + const field = isRecord(binding) && typeof binding["field"] === "string" ? binding["field"] : "id"; + bindings.push({ param, resource, field }); + if (itemUrl.includes(`{${param}}`) && !collectionUrlHas(param)) { + idField = field; + } + } + for (const [name, col] of Object.entries(cols)) { + if (!isRecord(col) || typeof col["urlTemplate"] !== "string") { + continue; + } + if (!firstCollection.has(resource)) { + firstCollection.set(resource, name); + } + const listQuery = {}; + if (isRecord(col["x-list-query"])) { + for (const [key, value] of Object.entries(col["x-list-query"])) { + listQuery[key] = asText(value); + } + } + collections.push({ + name, + resource, + url: col["urlTemplate"], + idField, + contextParams: pathVariables(col["urlTemplate"]), + listQuery, + method: listMethodOf(col), + listBody: isRecord(col["x-list-body"]) ? structuredClone(col["x-list-body"]) : {} + }); + } + } + const providers = /* @__PURE__ */ new Map(); + for (const { param, resource, field } of bindings) { + const collection = firstCollection.get(resource); + if (collection && !providers.has(param)) { + providers.set(param, { collection, field }); + } + } + return { collections, providers }; +} +function rootParameters(model) { + const parameters = /* @__PURE__ */ new Set(); + for (const collection of model.collections) { + for (const param of collection.contextParams) { + const provider = model.providers.get(param); + if (!provider || provider.collection === collection.name) { + parameters.add(param); + } + } + } + return [...parameters].sort(); +} +function upstreamOf(document) { + const servers = document["servers"]; + const first = Array.isArray(servers) ? servers[0] : void 0; + const raw = isRecord(first) ? first["url"] : void 0; + if (typeof raw !== "string" || !raw) { + throw new Error("OpenAPI document declares no servers"); + } + const url = new URL(raw); + if (url.protocol !== "https:" && url.protocol !== "http:") { + throw new Error("OpenAPI server must be an HTTP(S) URL"); + } + return url; +} +function listOperation(document, path, method) { + const operation = document.paths?.[path]?.[method === "POST" ? "post" : "get"]; + return isRecord(operation) ? operation : void 0; +} +function declaredQueryParameters(operation) { + return new Set((operation.parameters ?? []).filter((parameter) => isRecord(parameter) && parameter.in === "query").map((parameter) => parameter.name)); +} +function describeModel(document, model) { + return { + parameters: rootParameters(model), + collections: model.collections.map((c) => c.name), + upstream: upstreamOf(document).href + }; +} +function applySelection(document, model, selection) { + for (const override of selection?.query_overrides ?? []) { + const matches = model.collections.filter((c) => c.url === override.path); + const collection = matches[0]; + if (matches.length !== 1 || !collection) { + throw new Error(`Unknown or ambiguous collection path ${override.path}`); + } + const operation = listOperation(document, override.path, collection.method); + if (!operation) { + throw new Error(`Collection ${override.path} has no ${collection.method} operation`); + } + const declared = declaredQueryParameters(operation); + for (const [name, value] of Object.entries(override.values)) { + if (!declared.has(name)) { + throw new Error(`Unknown query parameter ${name} for ${override.path}`); + } + collection.listQuery[name] = asText(value); + } + } +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/read/ontology.js +var DATATYPES = { + string: "https://atomicdata.dev/datatypes/string", + timestamp: "https://atomicdata.dev/datatypes/timestamp", + date: "https://atomicdata.dev/datatypes/date", + integer: "https://atomicdata.dev/datatypes/integer", + float: "https://atomicdata.dev/datatypes/float", + boolean: "https://atomicdata.dev/datatypes/boolean", + json: "https://atomicdata.dev/datatypes/json" +}; +function ontologyShortname(name) { + return name.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).join("-"); +} +function datatypeOf(schema) { + switch (schema?.type) { + case "string": + return schema.format === "date-time" ? DATATYPES.timestamp : schema.format === "date" ? DATATYPES.date : DATATYPES.string; + case "integer": + return DATATYPES.integer; + case "number": + return DATATYPES.float; + case "boolean": + return DATATYPES.boolean; + default: + return void 0; + } +} +function flattenSchema(schema) { + if (!schema?.allOf) { + return schema ?? {}; + } + const { allOf, ...rest } = schema; + return allOf.map(flattenSchema).reduce((merged, branch) => ({ + ...merged, + required: [...merged.required ?? [], ...branch.required ?? []], + properties: { ...merged.properties, ...branch.properties } + }), rest); +} +function claim(claimed, original) { + const shortname = ontologyShortname(original); + const existing = claimed.get(shortname); + if (existing !== void 0 && existing !== original) { + throw new Error(`Ontology shortname ${shortname} is claimed by both ${existing} and ${original}`); + } + claimed.set(shortname, original); + return shortname; +} +function deriveOntology(document) { + const title = document.info?.title?.trim() ?? ""; + const base = title ? ontologyShortname(title) : "ontology"; + const terms = []; + const classNames = /* @__PURE__ */ new Map(); + const propertyNames = /* @__PURE__ */ new Map(); + const propertyIndex = /* @__PURE__ */ new Map(); + const agreed = /* @__PURE__ */ new Map(); + for (const [resource, def] of Object.entries(crudResourcesOf(document))) { + if (!isRecord(def)) { + continue; + } + const classShortname = claim(classNames, resource); + const schema = flattenSchema(def["schema"]); + const required = new Set(schema.required ?? []); + const requires = []; + const recommends = []; + for (const [field, fieldSchema] of Object.entries(schema.properties ?? {})) { + const shortname = claim(propertyNames, field); + const datatype = datatypeOf(fieldSchema); + let index = propertyIndex.get(shortname); + if (index === void 0) { + index = terms.length; + propertyIndex.set(shortname, index); + agreed.set(index, datatype); + terms.push({ + path: `${base}/property/${shortname}`, + kind: "property", + shortname, + description: typeof fieldSchema.description === "string" ? fieldSchema.description : `\`${field}\` of \`${resource}\`.`, + datatype: datatype ?? DATATYPES.json, + requires: [], + recommends: [] + }); + } else if (agreed.get(index) !== datatype) { + agreed.set(index, void 0); + terms[index].datatype = DATATYPES.json; + } + (required.has(field) ? requires : recommends).push(terms[index].path); + } + terms.push({ + path: `${base}/class/${classShortname}`, + kind: "class", + shortname: classShortname, + description: typeof def["description"] === "string" ? def["description"] : `The \`${resource}\` resource.`, + datatype: DATATYPES.json, + requires, + recommends + }); + } + return { + description: title ? `Derived from the "${title}" OpenAPI document.` : "Derived from an OpenAPI document.", + terms + }; +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/pagination/validate.js +var SCHEME_TYPES = /* @__PURE__ */ new Set(["pageNumber", "pageToken", "nextLink"]); +var REQUEST_ROLES = /* @__PURE__ */ new Set([ + "page", + "pageSize", + "offset", + "pageToken", + "cursor" +]); +var RESPONSE_ROLES = /* @__PURE__ */ new Set([ + "nextPageToken", + "nextCursor", + "nextLink", + "totalCount", + "totalPages", + "pageSize", + "currentPage" +]); +function isExtensionKey(key) { + return key.startsWith("x-"); +} +function validatePaginationScheme(name, scheme) { + const errors = []; + const path = `paginationSchemes.${name}`; + if (!SCHEME_TYPES.has(scheme.type)) { + errors.push(`${path}.type must be one of pageNumber, pageToken, or nextLink (got "${String(scheme.type)}")`); + } + if (!scheme.request && !scheme.response) { + errors.push(`${path} must define at least one of "request" or "response"`); + } + for (const [fieldName, field] of Object.entries(scheme.request?.queryParameters ?? {})) { + if (field.role && !isExtensionKey(field.role) && !REQUEST_ROLES.has(field.role)) { + errors.push(`${path}.request.queryParameters.${fieldName}.role is not a valid request role (got "${field.role}")`); + } + } + for (const [fieldName, field] of Object.entries(scheme.request?.bodyFields ?? {})) { + if (field.role && !isExtensionKey(field.role) && !REQUEST_ROLES.has(field.role)) { + errors.push(`${path}.request.bodyFields.${fieldName}.role is not a valid request role (got "${field.role}")`); + } + } + for (const [fieldName, field] of Object.entries(scheme.response?.bodyFields ?? {})) { + if (field.role && !isExtensionKey(field.role) && !RESPONSE_ROLES.has(field.role)) { + errors.push(`${path}.response.bodyFields.${fieldName}.role is not a valid response role (got "${field.role}")`); + } + } + for (const [fieldName, field] of Object.entries(scheme.response?.headers ?? {})) { + if (field.role && !isExtensionKey(field.role) && !RESPONSE_ROLES.has(field.role)) { + errors.push(`${path}.response.headers.${fieldName}.role is not a valid response role (got "${field.role}")`); + } + } + return errors; +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/pagination/autodetect.js +function validSchemes(document) { + const map = /* @__PURE__ */ new Map(); + const schemes = document.components?.paginationSchemes ?? {}; + for (const [name, scheme] of Object.entries(schemes)) { + if (validatePaginationScheme(name, scheme).length === 0) { + map.set(name, scheme); + } + } + return map; +} +function queryParamNames(operation) { + return new Set((operation.parameters ?? []).filter((parameter) => parameter.in === "query").map((parameter) => parameter.name)); +} +function bodyFieldNames(operation) { + const schema = operation.requestBody?.content?.["application/json"]?.schema; + return new Set(Object.keys(schema?.properties ?? {})); +} +function autoDetectMatches(scheme, operation) { + if (scheme.autoDetect === false) { + return false; + } + const options = typeof scheme.autoDetect === "object" ? scheme.autoDetect : {}; + const requireAll = options.requireAll ?? true; + const results = []; + if (options.matchQueryParams ?? true) { + const required = Object.keys(scheme.request?.queryParameters ?? {}); + if (required.length > 0) { + const declared = queryParamNames(operation); + results.push(required.every((name) => declared.has(name))); + } + } + if (options.matchBodyFields ?? true) { + const required = Object.keys(scheme.request?.bodyFields ?? {}); + if (required.length > 0) { + const declared = bodyFieldNames(operation); + results.push(required.every((name) => declared.has(name))); + } + } + if (results.length === 0) { + return false; + } + return requireAll ? results.every(Boolean) : results.some(Boolean); +} +function isPlainObject(value) { + return typeof value === "object" && value !== null && !Array.isArray(value); +} +function deepMerge(base, overrides) { + const result = { + ...base + }; + for (const [key, value] of Object.entries(overrides)) { + const existing = result[key]; + result[key] = isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value; + } + return result; +} +function resolveEffectiveScheme(document, operation) { + const schemes = validSchemes(document); + const explicit = operation["x-pagination"]; + if (Array.isArray(explicit) && explicit.length > 0) { + const application = explicit[0]; + const base = application ? schemes.get(application.scheme) : void 0; + if (!application || !base) { + return void 0; + } + return { + schemeName: application.scheme, + scheme: application.overrides ? deepMerge(base, application.overrides) : base + }; + } + for (const [schemeName, scheme] of schemes) { + if (autoDetectMatches(scheme, operation)) { + return { schemeName, scheme }; + } + } + return void 0; +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/pagination/items.js +var COMMON_ITEMS_FIELDS = ["items", "data", "results", "records", "content"]; +function effectiveProperties(schema) { + if (!schema) { + return {}; + } + if (schema.allOf) { + return schema.allOf.reduce((merged, branch) => ({ ...merged, ...effectiveProperties(branch) }), {}); + } + return { ...schema.properties ?? {} }; +} +function metadataFieldRoots(scheme) { + const roots = /* @__PURE__ */ new Set(); + for (const key of Object.keys(scheme?.response?.bodyFields ?? {})) { + roots.add(key.split(".")[0] ?? key); + } + return roots; +} +function locateItemsField(schema, scheme) { + const properties = effectiveProperties(schema); + const excluded = metadataFieldRoots(scheme); + for (const [name, propertySchema] of Object.entries(properties)) { + if (!excluded.has(name) && propertySchema.type === "array") { + return name; + } + } + return COMMON_ITEMS_FIELDS.find((name) => name in properties && !excluded.has(name)); +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/pagination/response-parser.js +function readNestedField(body, path) { + let node = body; + for (const segment of path.split(".")) { + if (typeof node !== "object" || node === null) { + return void 0; + } + node = node[segment]; + } + return node; +} +function setNestedField(body, path, value) { + const segments = path.split("."); + let node = body; + for (let i = 0; i < segments.length - 1; i += 1) { + const segment = segments[i]; + const child = node[segment]; + if (typeof child !== "object" || child === null) { + node[segment] = {}; + } + node = node[segment]; + } + node[segments[segments.length - 1]] = value; +} +function parseLinkHeader(header) { + if (!header) { + return null; + } + const parts = header.split(/,\s*(?=<)/); + for (const part of parts) { + const match = part.match(/^\s*<([^>]+)>(.*)/); + if (!match) { + continue; + } + const [, url, attrs] = match; + const relMatch = attrs?.match(/\brel\s*=\s*"?([^";,\s]+)"?/i); + if (relMatch?.[1]?.trim().toLowerCase() === "next") { + return url ?? null; + } + } + return null; +} +function toStringOrNull(value) { + if (value === null || value === void 0 || value === "") { + return null; + } + return String(value); +} +function toNumberOrNull(value) { + if (value === null || value === void 0) { + return null; + } + const n = Number(value); + return Number.isNaN(n) ? null : n; +} +function extractByRole(scheme, body, headers) { + const roles = /* @__PURE__ */ new Map(); + for (const [path, field] of Object.entries(scheme.response?.bodyFields ?? {})) { + if (!field.role) + continue; + const value = readNestedField(body, path); + if (value !== void 0) { + roles.set(field.role, value); + } + } + for (const [name, field] of Object.entries(scheme.response?.headers ?? {})) { + if (!field.role) + continue; + const raw = headers[name] ?? headers[name.toLowerCase()] ?? headers[name.toUpperCase()]; + if (raw === void 0) + continue; + if (field.role === "nextLink") { + const parsed = parseLinkHeader(raw); + if (parsed) + roles.set("nextLink", parsed); + } else { + roles.set(field.role, raw); + } + } + return roles; +} +function deriveHasNextPage(type, state, itemsFetchedSoFar) { + if (state.nextLink !== null || state.nextPageToken !== null) { + return true; + } + if (state.totalCount !== null && itemsFetchedSoFar !== void 0) { + return itemsFetchedSoFar < state.totalCount; + } + if (type === "pageNumber") { + if (state.currentPage !== null && state.totalPages !== null) { + return state.currentPage < state.totalPages; + } + if (state.currentPage !== null && state.totalCount !== null && state.pageSize !== null) { + return state.currentPage * state.pageSize < state.totalCount; + } + } + return false; +} +function parsePaginationState(scheme, body, headers = {}, itemsFetchedSoFar) { + const roles = extractByRole(scheme, body, headers); + const state = { + nextPageToken: toStringOrNull(roles.get("nextPageToken") ?? roles.get("nextCursor") ?? null), + nextLink: toStringOrNull(roles.get("nextLink") ?? null), + currentPage: toNumberOrNull(roles.get("currentPage") ?? null), + totalCount: toNumberOrNull(roles.get("totalCount") ?? null), + totalPages: toNumberOrNull(roles.get("totalPages") ?? null), + pageSize: toNumberOrNull(roles.get("pageSize") ?? null), + hasNextPage: false + }; + state.hasNextPage = deriveHasNextPage(scheme.type, state, itemsFetchedSoFar); + return state; +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/pagination/request-builder.js +function fieldsWithRole(scheme, role, locations = ["queryParameters"]) { + return locations.flatMap((location) => Object.entries(scheme.request?.[location] ?? {}).filter(([, field]) => field.role === role).map(([name]) => name)); +} +function cursorValues(scheme, cursor, pageSize, location) { + const values = {}; + const withRole = (role) => fieldsWithRole(scheme, role, [location]); + if (pageSize !== void 0) { + for (const name of withRole("pageSize")) { + values[name] = pageSize; + } + } + for (const name of withRole("offset")) { + values[name] = cursor.offset ?? 0; + } + for (const name of withRole("page")) { + values[name] = cursor.page ?? 1; + } + if (cursor.pageToken !== void 0) { + for (const name of [...withRole("pageToken"), ...withRole("cursor")]) { + values[name] = cursor.pageToken; + } + } + return values; +} +function buildQuery(scheme, cursor, pageSize) { + const query = {}; + for (const [name, value] of Object.entries(cursorValues(scheme, cursor, pageSize, "queryParameters"))) { + query[name] = String(value); + } + return query; +} +function buildBody(scheme, cursor, pageSize) { + const body = {}; + for (const [name, value] of Object.entries(cursorValues(scheme, cursor, pageSize, "bodyFields"))) { + setNestedField(body, name, value); + } + return body; +} +function nextCursor(scheme, cursor, state, itemsReturned) { + if (!state.hasNextPage) { + return null; + } + const both = ["queryParameters", "bodyFields"]; + switch (scheme.type) { + case "pageToken": + return state.nextPageToken !== null ? { pageToken: state.nextPageToken } : null; + case "nextLink": + return null; + case "pageNumber": + if (fieldsWithRole(scheme, "offset", both).length > 0) { + return { offset: (cursor.offset ?? 0) + itemsReturned }; + } + if (fieldsWithRole(scheme, "page", both).length > 0) { + return { page: (cursor.page ?? 1) + 1 }; + } + return null; + } +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/read/transport.js +function lowerCaseHeaders(headers) { + return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value])); +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/read/pages.js +var DEFAULT_READ_LIMITS = { + maxRequests: 1e4, + maxRecords: 5e3, + timeoutMs: 30 * 60 * 1e3, + maxRetries: 3 +}; +var BudgetExhausted = class extends Error { +}; +var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); +var Budget = class { + transport; + sleep; + limits; + deadline; + requests = 0; + constructor(transport, limits = {}, sleep = defaultSleep) { + this.transport = transport; + this.sleep = sleep; + this.limits = { ...DEFAULT_READ_LIMITS, ...limits }; + this.deadline = Date.now() + this.limits.timeoutMs; + } + async send(request) { + for (let retries = 0; ; retries += 1) { + if (Date.now() > this.deadline) { + throw new BudgetExhausted("Read timed out"); + } + this.requests += 1; + if (this.requests > this.limits.maxRequests) { + throw new BudgetExhausted(`Read exceeds ${this.limits.maxRequests} requests; narrow its scope`); + } + const raw = await this.transport(request); + const response = { ...raw, headers: lowerCaseHeaders(raw.headers) }; + if (response.status !== 429 || retries >= this.limits.maxRetries) { + return response; + } + const retryAfter = response.headers["retry-after"]; + const seconds = Number(retryAfter); + const at = retryAfter !== void 0 && retryAfter !== "" && Number.isFinite(seconds) ? Date.now() + Math.max(0, seconds) * 1e3 : retryAfter ? Date.parse(retryAfter) : NaN; + if (!Number.isFinite(at)) { + return response; + } + const delay = Math.max(0, at - Date.now()); + if (Date.now() + delay > this.deadline) { + throw new Error("API retry delay exceeds the remaining read time"); + } + await this.sleep(delay); + } + } +}; +var COMMON_ITEMS_FIELDS2 = ["items", "data", "results", "records", "content"]; +function pageItems(body, responseSchema, scheme) { + let array; + if (Array.isArray(body)) { + array = body; + } else if (isRecord(body)) { + const field = locateItemsField(responseSchema, scheme) ?? COMMON_ITEMS_FIELDS2.find((name) => Array.isArray(body[name])); + array = field === void 0 ? void 0 : body[field]; + } + if (!Array.isArray(array)) { + throw new Error("Could not locate the items array in the response"); + } + return array.filter(isRecord); +} +function bindPath(template, values) { + return template.replace(/\{([^}]+)\}/g, (_, name) => { + const value = values[name]; + if (value === void 0 || value === "") { + throw new Error(`Missing value for ${name}`); + } + return encodeURIComponent(value); + }); +} +function withBody(body, cursorFields) { + const merged = structuredClone(body); + const flat = []; + const collect = (node, prefix) => { + for (const [key, value] of Object.entries(node)) { + if (isRecord(value)) { + collect(value, `${prefix}${key}.`); + } else { + flat.push([`${prefix}${key}`, value]); + } + } + }; + collect(cursorFields, ""); + for (const [path, value] of flat) { + setNestedField(merged, path, value); + } + return merged; +} +async function* walkPages(walk) { + const { document, operation, budget, upstream } = walk; + const effective = resolveEffectiveScheme(document, operation); + const scheme = effective?.scheme; + const responseSchema = operation.responses?.["200"]?.content?.["application/json"]?.schema; + const basePath = upstream.pathname.replace(/\/$/, ""); + const seen = /* @__PURE__ */ new Set(); + let cursor = {}; + let next; + let itemsSoFar = 0; + for (; ; ) { + let url = next; + if (!url) { + url = new URL(upstream.href); + url.pathname = basePath + walk.path; + const query = { + ...walk.query, + ...scheme ? buildQuery(scheme, cursor, walk.pageSize) : {} + }; + for (const [key2, value] of Object.entries(query)) { + url.searchParams.set(key2, value); + } + } + const request = { + url, + method: walk.method, + headers: { accept: "application/json" } + }; + if (walk.method === "POST") { + request.headers["content-type"] = "application/json"; + request.body = JSON.stringify(next || !scheme ? walk.body : withBody(walk.body, buildBody(scheme, cursor, walk.pageSize))); + } + const key = `${request.method} ${url.href} ${request.body ?? ""}`; + if (seen.has(key)) { + throw new Error("Pagination repeated a page; stopping"); + } + seen.add(key); + const response = await budget.send(request); + if (response.status < 200 || response.status >= 300) { + throw new Error(`${request.method} ${url.pathname} responded ${response.status}`); + } + let body; + try { + body = JSON.parse(response.body); + } catch { + throw new Error(`${request.method} ${url.pathname} did not return JSON`); + } + const items = pageItems(body, responseSchema, scheme); + itemsSoFar += items.length; + yield { url, items }; + if (!scheme) { + return; + } + const state = parsePaginationState(scheme, isRecord(body) ? body : {}, response.headers, itemsSoFar); + if (!state.hasNextPage) { + return; + } + if (scheme.type === "nextLink" || state.nextLink !== null && state.nextPageToken === null) { + if (state.nextLink === null) { + return; + } + const link = new URL(state.nextLink, url); + if (link.origin !== upstream.origin || link.username || link.password || link.hash) { + throw new Error("Pagination left the API origin"); + } + next = link; + } else { + if (scheme.type === "pageNumber" && items.length === 0) { + return; + } + const following = nextCursor(scheme, cursor, state, items.length); + if (!following) { + return; + } + cursor = following; + next = void 0; + } + } +} + +// integrations/pets/node_modules/.pnpm/syncables@0.18.0/node_modules/syncables/build/src/read/read.js +var resolvedCache = /* @__PURE__ */ new WeakMap(); +function resolved(document) { + let result = resolvedCache.get(document); + if (!result) { + result = resolveRefs(document); + resolvedCache.set(document, result); + } + return result; +} +function describePlatform(document) { + const doc = resolved(document); + return describeModel(doc, discoverReadModel(doc)); +} +var ProbeDone = class extends Error { +}; +function invocations(collection, model, constants, origins) { + const groups = /* @__PURE__ */ new Map(); + for (const param of collection.contextParams) { + if (param in constants) { + continue; + } + const provider = model.providers.get(param); + if (!provider) { + continue; + } + groups.set(provider.collection, [ + ...groups.get(provider.collection) ?? [], + { param, field: provider.field } + ]); + } + let combos = [{ ...constants }]; + for (const [source, params] of groups) { + const next = []; + for (const combo of combos) { + for (const parent of origins.get(source) ?? []) { + const values = { ...parent.path, ...combo }; + for (const { param, field } of params) { + values[param] = asText(parent.value[field]); + } + if (params.every(({ param }) => values[param])) { + next.push(values); + } + } + } + combos = next; + } + const seen = /* @__PURE__ */ new Set(); + return combos.filter((combo) => { + const key = JSON.stringify(collection.contextParams.map((p) => combo[p] ?? "")); + if (seen.has(key)) { + return false; + } + seen.add(key); + return true; + }); +} +var TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/i; +function typedValue(value, datatype) { + if (value === null || value === void 0) { + return void 0; + } + if (datatype === DATATYPES.timestamp) { + if (typeof value !== "string" || !TIMESTAMP.test(value)) { + throw new Error("Invalid provider timestamp"); + } + return Date.parse(value); + } + return value; +} +async function readPlatform(document, options) { + const doc = resolved(document); + const budget = new Budget(options.transport, options.limits, options.sleep); + const model = discoverReadModel(doc); + applySelection(doc, model, options.selection); + const upstream = upstreamOf(doc); + const constants = options.constants; + for (const param of rootParameters(model)) { + if (!constants[param]) { + throw new Error(`Enter a value for ${param}`); + } + } + const ontology = options.probe ? { description: "", terms: [] } : deriveOntology(doc); + const properties = new Map(ontology.terms.filter((t) => t.kind === "property").map((t) => [t.shortname, t.datatype])); + const records = []; + const identities = /* @__PURE__ */ new Set(); + const errors = []; + const origins = /* @__PURE__ */ new Map(); + const walk = async (collection, path) => { + const operation = listOperation(doc, collection.url, collection.method); + if (!operation) { + throw new Error(`${collection.url} declares no ${collection.method} operation`); + } + const namespace = collection.contextParams.map((p) => path[p] ?? "").join("/"); + const out = []; + for await (const page of walkPages({ + document: doc, + operation, + budget, + upstream, + path: bindPath(collection.url, path), + method: collection.method, + query: collection.listQuery, + body: collection.listBody + })) { + if (options.probe) { + throw new ProbeDone(); + } + for (const value of page.items) { + const id = asText(value[collection.idField]); + const key = JSON.stringify([collection.resource, namespace, id]); + if (!id || identities.has(key)) { + throw new Error("Missing or repeated record identity; pagination may not be forwarded by the proxy"); + } + if (records.length >= budget.limits.maxRecords) { + throw new BudgetExhausted(`Read exceeds ${budget.limits.maxRecords} records; narrow its scope`); + } + identities.add(key); + const values = {}; + for (const [field, raw] of Object.entries(value)) { + const shortname = ontologyShortname(field); + const datatype = properties.get(shortname); + if (!datatype) { + continue; + } + const typed = typedValue(raw, datatype); + if (typed !== void 0) { + values[shortname] = typed; + } + } + const name = [value["title"], value["summary"], value["name"]].find((v) => typeof v === "string" && v !== ""); + records.push({ + resource: ontologyShortname(collection.resource), + namespace, + id, + name: name ?? id, + values + }); + out.push({ value, path }); + } + } + return out; + }; + let pending = [...model.collections]; + while (pending.length) { + const waiting = []; + let progressed = false; + for (const collection of pending) { + const sources = collection.contextParams.filter((p) => !(p in constants)).map((p) => model.providers.get(p)?.collection); + if (sources.some((s) => s === void 0 || s === collection.name)) { + errors.push(`${collection.name}: its context has no provider`); + progressed = true; + continue; + } + if (!sources.every((source) => origins.has(source))) { + waiting.push(collection); + continue; + } + progressed = true; + const read = []; + for (const path of invocations(collection, model, constants, origins)) { + try { + read.push(...await walk(collection, path)); + } catch (error) { + if (error instanceof ProbeDone) { + return { + platform: options.platform, + ontology, + records: [], + errors: [] + }; + } + if (options.probe) { + throw error; + } + errors.push(`${collection.name}: ${error.message}`); + if (error instanceof BudgetExhausted) { + pending = []; + break; + } + } + } + origins.set(collection.name, read); + if (!pending.length) { + break; + } + } + if (!pending.length) { + break; + } + if (!progressed) { + for (const c of waiting) { + errors.push(`${c.name}: its parent collection could not be read`); + } + break; + } + pending = waiting; + } + if (options.probe) { + throw new Error("No collection available to check"); + } + if (!records.length && errors.length) { + throw new Error(`Read incomplete: ${errors.join("; ")}`); + } + return { platform: options.platform, ontology, records, errors }; +} + +// integrations/pets/app/openapi.json +var openapi_default = { + openapi: "3.0.3", + info: { + title: "Pets", + version: "1.0.0" + }, + servers: [ + { + url: "https://pets.example" + } + ], + paths: { + "/pets": { + get: { + "x-pagination": [ + { + scheme: "nextLink" + } + ], + responses: { + "200": { + description: "Pets", + content: { + "application/json": { + schema: { + type: "array", + items: { + $ref: "#/components/schemas/Pet" + } + } + } + } + } + } + } + } + }, + components: { + paginationSchemes: { + nextLink: { + type: "nextLink", + response: { + headers: { + Link: { + role: "nextLink" + } + } + } + } + }, + schemas: { + Pet: { + type: "object", + required: ["id", "name"], + properties: { + id: { + type: "integer" + }, + name: { + type: "string" + }, + species: { + type: "string" + }, + age: { + type: "integer" + }, + vaccinated: { + type: "boolean" + }, + weight: { + type: "number" + }, + updated_at: { + type: "string", + format: "date-time" + } + } + } + }, + crudResources: { + pet: { + schema: { + $ref: "#/components/schemas/Pet" + }, + identity: { + urlTemplate: "/pets/{pet_id}", + bindings: { + pet_id: { + field: "id" + } + } + }, + collections: { + pets: { + urlTemplate: "/pets" + } + } + } + } + } +}; + +// integrations/pets/app/sync.ts +var PLATFORM = "pets"; +var PETS_DOCUMENT = openapi_default; +var A = "https://atomicdata.dev"; +var PARENT = `${A}/properties/parent`; +var IS_A = `${A}/properties/isA`; +var NAME = `${A}/properties/name`; +var SHORTNAME = `${A}/properties/shortname`; +var DESCRIPTION = `${A}/properties/description`; +var DATATYPE = `${A}/properties/datatype`; +var RECOMMENDS = `${A}/properties/recommends`; +var PROPERTIES = `${A}/properties/properties`; +var PROPERTY_CLASS = `${A}/classes/Property`; +function displayName(shortname) { + const words = shortname.split("-").join(" "); + return `${words[0]?.toUpperCase() ?? ""}${words.slice(1)}`; +} +var asList = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : []; +async function syncPets(store, transport, { read = readPlatform } = {}) { + const data = await store.getData(); + if (!data?.rowClass) + throw new Error("This app has no table with a row class to sync into."); + const result = await read(PETS_DOCUMENT, { + platform: PLATFORM, + constants: {}, + transport + }); + const klass = await store.getResource(data.rowClass); + const ontologySubject = klass.get(PARENT); + if (typeof ontologySubject !== "string") + throw new Error("The row class has no parent ontology to add fields to."); + const properties = await ensureProperties( + store, + ontologySubject, + result.ontology.terms.filter( + (t) => t.kind === "property" && t.shortname !== "name" + ) + ); + const recommends = asList(klass.get(RECOMMENDS)); + const wanted = [NAME, ...properties.values()]; + const merged = [ + ...recommends, + ...wanted.filter((s) => !recommends.includes(s)) + ]; + if (merged.length !== recommends.length || klass.get(NAME) !== "Pet") { + await klass.set(RECOMMENDS, merged).set(NAME, "Pet").save(); + } + const table = await store.getResource(data.table); + if (table.get(NAME) !== "Pets") await table.set(NAME, "Pets").save(); + const idProperty = properties.get("id"); + if (!idProperty) throw new Error("The Pets API document has no id field."); + const existing = /* @__PURE__ */ new Map(); + for (const subject of await store.query({ + property: PARENT, + value: data.table + })) { + const row = await store.getResource(subject); + const id = row.get(idProperty); + if (id !== void 0 && id !== null) existing.set(String(id), row); + } + const summary = { + total: result.records.length, + added: 0, + updated: 0, + unchanged: 0, + errors: result.errors + }; + for (const record of result.records) { + const propVals = { [NAME]: record.name }; + for (const [shortname, value] of Object.entries(record.values)) { + const property = properties.get(shortname); + if (property) propVals[property] = value; + } + const row = existing.get(record.id); + if (!row) { + await store.newResource({ + parent: data.table, + isA: [data.rowClass], + propVals + }); + summary.added++; + continue; + } + const changed = Object.entries(propVals).filter( + ([property, value]) => row.get(property) !== value + ); + if (changed.length === 0) { + summary.unchanged++; + continue; + } + for (const [property, value] of changed) row.set(property, value); + await row.save(); + summary.updated++; + } + return summary; +} +async function ensureProperties(store, ontologySubject, terms) { + const ontology = await store.getResource(ontologySubject); + const listed = asList(ontology.get(PROPERTIES)); + const byShortname = /* @__PURE__ */ new Map(); + for (const subject of listed) { + const property = await store.getResource(subject); + const shortname = property.get(SHORTNAME); + if (typeof shortname === "string") byShortname.set(shortname, subject); + } + const created = []; + const out = /* @__PURE__ */ new Map(); + for (const term of terms) { + let subject = byShortname.get(term.shortname); + if (!subject) { + const name = displayName(term.shortname); + const property = await store.newResource({ + parent: ontologySubject, + isA: [PROPERTY_CLASS], + propVals: { + [SHORTNAME]: term.shortname, + [NAME]: name, + [DESCRIPTION]: term.description || `${name} of a pet, from the Pets API.`, + [DATATYPE]: term.datatype + } + }); + subject = property.subject; + created.push(subject); + } + out.set(term.shortname, subject); + } + if (created.length > 0) + await ontology.set(PROPERTIES, [...listed, ...created]).save(); + return out; +} + +// integrations/pets/app/transport.ts +var RECONNECT_CODES = [ + "unknown_connection", + "not_delegated", + "capability_scope", + "platform_mismatch", + "credential_refresh_failed" +]; +var REFUSAL_CODES = [ + ...RECONNECT_CODES, + "missing_signature", + "unsupported_signature_version", + "invalid_agent", + "agent_key_mismatch", + "stale_timestamp", + "bad_signature", + "replayed", + "invalid_capability", + "capability_expired", + "capability_too_long", + "wrong_audience", + "capability_key_mismatch", + "not_owner", + "access_denied" +]; +function proxyRefusal(response) { + const body = response.body; + const code = typeof body?.error === "string" ? body.error : void 0; + if (response.status < 400 || !code || !REFUSAL_CODES.includes(code)) + return void 0; + const detail = typeof body?.message === "string" ? `: ${body.message}` : ""; + return new Error( + RECONNECT_CODES.includes(code) ? `The integration proxy refused this connection (${code}${detail}). Connect again.` : `The integration proxy refused the request (${code}${detail}).` + ); +} +function relayTransport(proxy, reference, upstream) { + const base = new URL(upstream); + const prefix = base.pathname.replace(/\/$/, ""); + return async (request) => { + const { url } = request; + if (url.origin !== base.origin || prefix !== "" && url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`)) + throw new Error(`Refusing a request outside ${upstream}: ${url.href}`); + const path = `${url.pathname.slice(prefix.length) || "/"}${url.search}`; + const response = await proxy.request({ + ...reference, + path, + method: request.method, + ...request.body !== void 0 ? { body: request.body } : {} + }); + const refused = proxyRefusal(response); + if (refused) throw refused; + return { + status: response.status, + headers: response.headers ?? {}, + body: typeof response.body === "string" ? response.body : JSON.stringify(response.body ?? null) + }; + }; +} + +// integrations/pets/app/controller.ts +function describe(state) { + switch (state.kind) { + case "loading": + return "Loading\u2026"; + case "no-relay": + return "This host cannot reach the integration proxy for apps yet."; + case "disconnected": + return "Not connected. Connect your Pets account to import your pets."; + case "connecting": + return "Waiting for you to confirm the connection\u2026"; + case "ready": + return "Connected."; + case "syncing": + return "Syncing\u2026"; + case "synced": { + const s = state.summary; + const errors = s.errors.length ? ` Skipped: ${s.errors.join("; ")}` : ""; + return `Last synced ${state.at.toLocaleTimeString()}: ${s.total} pets (${s.added} added, ${s.updated} updated, ${s.unchanged} unchanged).${errors}`; + } + case "error": + return `Sync failed: ${state.message}`; + } +} +var message = (error) => error instanceof Error ? error.message : String(error); +function createController(store, render, sync = syncPets) { + let state = { kind: "loading" }; + const set = (next) => { + state = next; + render(state); + }; + const upstream = describePlatform(PETS_DOCUMENT).upstream; + return { + state: () => state, + /** + * Finds this app's connection and starts one sync when there is one. + * Resolves once the connection is known, not when the sync ends, so the + * host sees the view as rendered straight away. + */ + async load() { + const proxy = store.proxy; + if (!proxy) { + set({ kind: "no-relay" }); + return {}; + } + const [connection] = await proxy.connections({ platform: PLATFORM }); + if (!connection) { + set({ kind: "disconnected" }); + return {}; + } + set({ kind: "ready", connection }); + return { syncing: this.sync() }; + }, + async connect() { + const proxy = store.proxy; + if (!proxy) return set({ kind: "no-relay" }); + set({ kind: "connecting" }); + try { + const result = await proxy.connect({ platform: PLATFORM }); + if (result?.status === "connected") await this.load(); + else set({ kind: "disconnected" }); + } catch (error) { + set({ kind: "error", message: message(error) }); + } + }, + async sync() { + const proxy = store.proxy; + if (!proxy) return set({ kind: "no-relay" }); + if (!("connection" in state) || !state.connection) return; + if (state.kind === "syncing") return; + const connection = state.connection; + set({ kind: "syncing", connection }); + try { + const summary = await sync( + store, + relayTransport(proxy, connection, upstream) + ); + set({ kind: "synced", connection, at: /* @__PURE__ */ new Date(), summary }); + } catch (error) { + set({ kind: "error", connection, message: message(error) }); + } + } + }; +} + +// integrations/pets/app/main.ts +async function view({ root, store }) { + const doc = root.ownerDocument; + const heading = doc.createElement("h1"); + heading.textContent = "Pets"; + const status = doc.createElement("p"); + status.setAttribute("role", "status"); + const connect = doc.createElement("button"); + connect.type = "button"; + connect.textContent = "Connect Pets"; + const sync = doc.createElement("button"); + sync.type = "button"; + sync.textContent = "Sync now"; + root.style.fontFamily = "system-ui, sans-serif"; + root.style.padding = "1rem"; + root.replaceChildren(heading, status, connect, sync); + const render = (state) => { + status.textContent = describe(state); + connect.hidden = !(state.kind === "disconnected" || state.kind === "error" && !state.connection); + sync.hidden = !(state.kind === "ready" || state.kind === "synced" || state.kind === "syncing" || state.kind === "error" && !!state.connection); + sync.disabled = state.kind === "syncing"; + }; + const controller = createController(store, render); + render(controller.state()); + connect.addEventListener("click", () => void controller.connect()); + sync.addEventListener("click", () => void controller.sync()); + await controller.load().catch((error) => { + status.textContent = `Could not load: ${error instanceof Error ? error.message : String(error)}`; + }); +} +export { + view +}; diff --git a/integrations/catalog.json b/integrations/catalog.json index eec27c7c1..ece13515a 100644 --- a/integrations/catalog.json +++ b/integrations/catalog.json @@ -332,9 +332,9 @@ "https://atomicdata.dev/integrations/properties/events": "Connect once, then Sync now whenever you want the latest pets. Nothing runs in the background.", "https://atomicdata.dev/integrations/properties/limitation": "Demo provider only, not a real account. Import only: nothing is written back. Keep the browser open while syncing.", "https://atomicdata.dev/integrations/properties/keywords": "pets demo example sample drive app ontology test touch points localthought", - "https://atomicdata.dev/integrations/properties/version": "0.1.0", - "https://atomicdata.dev/integrations/properties/app-module": "https://ontola.github.io/atomic-plugins/apps/pets/0.1.0/ui.js", - "https://atomicdata.dev/integrations/properties/app-module-integrity": "sha384-yzC96dzMDYdRJBZy7O5/wGDfMx7FoyPMmer51AQJ9M7IL9IfhMFbVOsbQR3Mw4pD", + "https://atomicdata.dev/integrations/properties/version": "0.1.1", + "https://atomicdata.dev/integrations/properties/app-module": "https://ontola.github.io/atomic-plugins/apps/pets/0.1.1/ui.js", + "https://atomicdata.dev/integrations/properties/app-module-integrity": "sha384-41Lz+YXgQJNRqGsiGtduk4wE6fVURecH8sK68Rkwz6GS/EvcG974e69xvj3hEN8i", "https://atomicdata.dev/integrations/properties/app-row-name": "Pet", "https://atomicdata.dev/integrations/properties/app-row-name-plural": "Pets" } diff --git a/integrations/pets/package.json b/integrations/pets/package.json index f9629125f..8ce225e74 100644 --- a/integrations/pets/package.json +++ b/integrations/pets/package.json @@ -1,7 +1,7 @@ { "name": "@atomic-integrations/pets", "private": true, - "version": "0.1.0", + "version": "0.1.1", "type": "module", "description": "Trivial demo Pets collection; no external provider", "dependencies": { From 0e3bfd32e1063653da856819f8eb2f33e33d5dd5 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 24 Sep 2026 17:09:26 +0200 Subject: [PATCH 6/8] e2e: every drive-app spec connects through the proxy 0.2 flow (#54 phase 2) - Consent bar -> the mock proxy's /connect (no user_id) -> back to /app/integrations, where the page redeems signed with the user key and delegates to the app agent; the frame then calls the proxy with a capability and its own key. The consent button is the real proxy's ("... with this destination"); Clockify, an API-key platform, takes the key on the proxy's page. - The localStorage connection-code assertions are gone. Specs instead check at the mock (GET /__mock/connections) that one connection exists, owned by the signed-in agent and delegated once, and that the page kept no proxy state in localStorage. - pets: revoke the delegation at the proxy, then "Use existing connection" gets the app back without the consent page. - calendar: the lost-response route matches /proxy/*/google-calendar/**, and no reconnect follows it (nothing is spent any more). - issue-tracker: GitHub-side reads and edits use the github-issues fixture's new drivers (snapshot, updateIssue) instead of spending the page's code. - tooling: serve.mjs passes MOCK_PROXY_BASE_URL (= INTEGRATION_PROXY_URL = ATOMIC_INTEGRATION_PROXY_URL, one mockProxyOrigin()); TENANT_SECRET is gone. Co-Authored-By: Claude Opus 5.5 --- integrations/calendar/e2e/calendar.spec.ts | 69 +++++++--- .../issue-tracker/e2e/issue-tracker.spec.ts | 122 +++++++++++------- .../fixtures/github-issues/scenario.mjs | 2 + integrations/notion/e2e/notion.spec.ts | 20 +-- integrations/pets/e2e/pets.spec.ts | 107 +++++++++++++-- integrations/timesheets/e2e/clockify.spec.ts | 62 +++++++-- integrations/tooling/run-lane.mjs | 4 +- integrations/tooling/serve.mjs | 27 +++- 8 files changed, 298 insertions(+), 115 deletions(-) diff --git a/integrations/calendar/e2e/calendar.spec.ts b/integrations/calendar/e2e/calendar.spec.ts index 6530c1823..d6b761afc 100644 --- a/integrations/calendar/e2e/calendar.spec.ts +++ b/integrations/calendar/e2e/calendar.spec.ts @@ -3,9 +3,12 @@ * The Calendar drive app (`../app/`) end to end, in its null-origin plugin * frame on the pinned atomic-server: connect Google Calendar through the * host's consent bar and the mock integration proxy, choose one calendar, - * import it through the host's proxy relay, refresh after a Google-side - * edit, then preview and send a local edit — including an ETag conflict and - * a write whose response is lost. + * import it, refresh after a Google-side edit, then preview and send a local + * edit — including an ETag conflict and a write whose response is lost. + * + * The frame calls the proxy itself (#54 phase 2): a capability from the page, + * each request signed with the frame's own key, `If-Match` passed through. + * The mock proxy checks every signature the way the real one does. * * The provider is the mock proxy's stateful google-calendar fixture * (`../fixtures/google-calendar/scenario.mjs`). Its Google-side edits are @@ -138,10 +141,10 @@ test.describe('calendar drive app', () => { expect((await driver('state', [])).writes).toHaveLength(1); // A lost response: the PATCH reaches the proxy, its answer never - // reaches the page. The app says it can't know, and asks to reconnect. + // reaches the frame. The app says it can't know. await app.getByRole('button', { name: 'Refresh' }).click(); await expect(review).toContainText('Renamed here → Renamed twice'); - await page.route('**/proxy/google-calendar/**', async route => { + await page.route('**/proxy/*/google-calendar/**', async route => { if (route.request().method() !== 'PATCH') return route.continue(); await route.fetch(); await route.abort('connectionreset'); @@ -149,27 +152,29 @@ test.describe('calendar drive app', () => { await sendOne.click(); await expect(status).toContainText('may or may not have applied'); await expect(sent).toContainText('Unknown whether Google applied it'); - await page.unroute('**/proxy/google-calendar/**'); + await page.unroute('**/proxy/*/google-calendar/**'); expect((await driver('state', [])).writes).toHaveLength(2); + // Nothing was spent (there are no connection codes any more): the same + // connection refreshes straight away. Google has the change, so the new + // preview agrees: nothing to review. await app.getByRole('button', { name: 'Refresh' }).click(); - await expect( - app.getByRole('button', { name: 'Connect Google Calendar' }), - ).toBeVisible(); - await connectThroughHost(page, app); - // Google has the change, so the new preview agrees: nothing to review. await expect(status).toContainText('Last refreshed', { timeout: 30_000 }); await expect(status).not.toContainText('to review'); await expect(status).not.toContainText('conflict'); expect((await driver('state', [])).writes).toHaveLength(2); - // The frame never held the rotating code; the page keeps it. - const stored = await page.evaluate(() => - Object.keys(localStorage).filter(k => - k.startsWith('atomic-proxy-connection-v1:'), - ), + // The connection lives at the proxy, owned by the signed-in user and + // delegated to this app; the page keeps nothing credential-like. + const connections = await proxyConnections('google-calendar'); + expect(connections).toHaveLength(1); + expect(connections[0].owner).toBe(await signedInAgent(page)); + expect(connections[0].delegations).toHaveLength(1); + expect(await page.evaluate(() => Object.keys(localStorage))).not.toEqual( + expect.arrayContaining([ + expect.stringMatching(/^atomic-proxy-connect|connection-v1/), + ]), ); - expect(stored.length).toBeGreaterThanOrEqual(1); }); }); @@ -185,13 +190,41 @@ async function connectThroughHost(page: Page, app: FrameLocator) { ).toBeVisible(); await page .getByRole('button', { - name: 'Use LocalThought to sync Google Calendar with your Atomic Data Hub', + name: 'Use LocalThought to sync Google Calendar with this destination', exact: true, }) .click(); await expect(page).not.toHaveURL(/connection_code=|integration_state=/); } +interface MockConnection { + connection_id: string; + platform: string; + owner: string; + delegations: { agent: string; label: string | null }[]; +} + +/** The mock proxy's connections for `platform` (test-side introspection). */ +async function proxyConnections(platform: string): Promise { + const response = await fetch( + `${process.env.INTEGRATION_PROXY_URL}/__mock/connections`, + ); + const { connections } = (await response.json()) as { + connections: MockConnection[]; + }; + + return connections.filter(c => c.platform === platform); +} + +/** The signed-in agent as the proxy names it: `atomic:agent:`. */ +async function signedInAgent(page: Page): Promise { + const key = await page.evaluate(() => + window.store!.getAgent()!.getPublicKey(), + ); + + return `atomic:agent:${Buffer.from(key, 'base64').toString('base64url')}`; +} + /** Calls a mock-proxy test driver of the google-calendar fixture. */ async function driver(name: string, args: unknown[]) { const response = await fetch( diff --git a/integrations/issue-tracker/e2e/issue-tracker.spec.ts b/integrations/issue-tracker/e2e/issue-tracker.spec.ts index 37b40ca24..746af357c 100644 --- a/integrations/issue-tracker/e2e/issue-tracker.spec.ts +++ b/integrations/issue-tracker/e2e/issue-tracker.spec.ts @@ -15,10 +15,11 @@ * 4. Conflict recovery: the same title edited in the table and on GitHub * pauses sync; "Keep GitHub's version" settles it. * - * GitHub-side reads and edits go straight to the mock proxy with the - * connection this browser holds (the host page's localStorage, under its - * Web Lock), standing in for someone working on GitHub. The app never sees - * that code. + * GitHub-side reads and edits go through the mock's test drivers for the + * github-issues fixture (`POST /fixture/github-issues/`), standing + * in for someone working on GitHub. The connection itself lives at the + * proxy (#54 phase 2): the page redeems and delegates it, and the frame + * calls the proxy with a capability and its own key. * * Needs an atomic-server with the host relay (atomic-server#1657, in the * pin). Run it the way CI does: @@ -74,7 +75,7 @@ test.describe('GitHub issues drive app', () => { ).toBeVisible(); await page .getByRole('button', { - name: 'Use LocalThought to sync GitHub Issues with your Atomic Data Hub', + name: 'Use LocalThought to sync GitHub Issues with this destination', exact: true, }) .click(); @@ -116,7 +117,7 @@ test.describe('GitHub issues drive app', () => { 'Update #1: status Todo → Done (close it)', { timeout: 30_000 }, ); - expect((await github(page, 'GET', '/issues/1')).state).toBe('open'); + expect((await github('GET', '/issues/1')).state).toBe('open'); await review .getByRole('button', { name: 'Send 1 change to GitHub' }) .click(); @@ -124,13 +125,13 @@ test.describe('GitHub issues drive app', () => { '1 sent to GitHub', { timeout: 30_000 }, ); - expect((await github(page, 'GET', '/issues/1')).state).toBe('closed'); + expect((await github('GET', '/issues/1')).state).toBe('closed'); await expect(review).toBeHidden(); // 4. Conflict: #2's title edited on both sides since the last sync. const second = await subjectOf(app, '#2 '); await setName(page, second, 'Export as CSV (edited here)'); - await github(page, 'PATCH', '/issues/2', { + await github('PATCH', '/issues/2', { title: 'Export as CSV (edited on GitHub)', }); await app.getByRole('button', { name: 'Sync now' }).click(); @@ -144,17 +145,21 @@ test.describe('GitHub issues drive app', () => { { timeout: 30_000 }, ); await expect(issues).toContainText('#2 Export as CSV (edited on GitHub)'); - expect((await github(page, 'GET', '/issues/2')).title).toBe( + expect((await github('GET', '/issues/2')).title).toBe( 'Export as CSV (edited on GitHub)', ); - // The frame never saw the rotating code; the page holds it, the drive does not. - const stored = await page.evaluate(() => - Object.keys(localStorage).filter(k => - k.startsWith('atomic-proxy-connection-v1:'), - ), + // The connection lives at the proxy, owned by the signed-in user and + // delegated to this app; the page keeps nothing credential-like. + const connections = await proxyConnections('github-issues'); + expect(connections).toHaveLength(1); + expect(connections[0].owner).toBe(await signedInAgent(page)); + expect(connections[0].delegations).toHaveLength(1); + expect(await page.evaluate(() => Object.keys(localStorage))).not.toEqual( + expect.arrayContaining([ + expect.stringMatching(/^atomic-proxy-connect|connection-v1/), + ]), ); - expect(stored).toHaveLength(1); }); }); @@ -213,48 +218,65 @@ async function setStatus(page: Page, subject: string, shortname: string) { } /** - * One GitHub call straight to the mock proxy, spending and rotating the - * connection code the host page holds, under the same Web Lock the host's - * relay takes. Stands in for someone working on GitHub directly. + * Someone working on GitHub directly: the github-issues fixture's test + * drivers on the mock proxy (`snapshot`, `updateIssue`), not the app's + * connection. */ async function github( - page: Page, method: 'GET' | 'PATCH', path: string, body?: Record, ): Promise> { - return page.evaluate( - async ({ verb, route, payload, repository }) => { - const key = Object.keys(localStorage).find(k => { - if (!k.startsWith('atomic-proxy-connection-v1:')) return false; - const c = JSON.parse(localStorage.getItem(k)!); - - return c.ready && c.platform === 'github-issues'; - }); - if (!key) throw new Error('No github-issues connection in this page'); - - return navigator.locks.request(key, async () => { - const c = JSON.parse(localStorage.getItem(key)!); - const response = await fetch( - `${c.origin}/proxy/github-issues/repos/${repository}${route}`, - { - method: verb, - headers: { - Authorization: `Bearer ${c.code}`, - ...(payload ? { 'Content-Type': 'application/json' } : {}), - }, - ...(payload ? { body: JSON.stringify(payload) } : {}), - }, - ); - const next = response.headers.get('x-connection-code'); - if (!next) throw new Error('The mock proxy did not rotate the code'); - localStorage.setItem(key, JSON.stringify({ ...c, code: next })); - - return response.json(); - }); - }, - { verb: method, route: path, payload: body, repository: REPOSITORY }, + const number = Number(/^\/issues\/(\d+)$/.exec(path)?.[1]); + if (!number) throw new Error(`Unsupported GitHub path ${path}`); + + const call = async (name: string, args: unknown[]) => { + const response = await fetch( + `${process.env.INTEGRATION_PROXY_URL}/fixture/github-issues/${name}`, + { method: 'POST', body: JSON.stringify(args) }, + ); + if (!response.ok) throw new Error(`${name}: HTTP ${response.status}`); + + return response.json(); + }; + + if (method === 'PATCH') + return call('updateIssue', [REPOSITORY, number, body ?? {}]); + const { issues } = (await call('snapshot', [REPOSITORY])) as { + issues: { number: number }[]; + }; + const issue = issues.find(i => i.number === number); + if (!issue) throw new Error(`No issue #${number}`); + + return issue; +} + +interface MockConnection { + connection_id: string; + platform: string; + owner: string; + delegations: { agent: string; label: string | null }[]; +} + +/** The mock proxy's connections for `platform` (test-side introspection). */ +async function proxyConnections(platform: string): Promise { + const response = await fetch( + `${process.env.INTEGRATION_PROXY_URL}/__mock/connections`, ); + const { connections } = (await response.json()) as { + connections: MockConnection[]; + }; + + return connections.filter(c => c.platform === platform); +} + +/** The signed-in agent as the proxy names it: `atomic:agent:`. */ +async function signedInAgent(page: Page): Promise { + const key = await page.evaluate(() => + window.store!.getAgent()!.getPublicKey(), + ); + + return `atomic:agent:${Buffer.from(key, 'base64').toString('base64url')}`; } /** diff --git a/integrations/issue-tracker/fixtures/github-issues/scenario.mjs b/integrations/issue-tracker/fixtures/github-issues/scenario.mjs index 3e5e8bd88..4cd0e570e 100644 --- a/integrations/issue-tracker/fixtures/github-issues/scenario.mjs +++ b/integrations/issue-tracker/fixtures/github-issues/scenario.mjs @@ -150,4 +150,6 @@ export default { title: 'GitHub Issues', jsonBody: true, create: githubTracker, + // For the drive app's e2e: someone reading and editing on GitHub itself. + drivers: ['snapshot', 'updateIssue'], }; diff --git a/integrations/notion/e2e/notion.spec.ts b/integrations/notion/e2e/notion.spec.ts index 4d06e8db9..f1a3629be 100644 --- a/integrations/notion/e2e/notion.spec.ts +++ b/integrations/notion/e2e/notion.spec.ts @@ -1,14 +1,14 @@ // @wc-ignore-file /** * The Notion drive plugin (`../app/`) end to end: an app in the drive runs - * `dist/ui.js` in its null-origin frame, connects through the host's - * integration-proxy relay (#52), and imports the mock proxy's notion fixture - * through syncables/browser, cursor in the POST body included. + * `dist/ui.js` in its null-origin frame, connects through the host's consent + * bar and the mock integration proxy, and imports the mock proxy's notion + * fixture through syncables/browser, cursor in the POST body included. * - * It needs an atomic-server with #52's relay (`store.proxy`, the host consent - * bar and the connect return): ontola/atomic-server#1657, merged into - * `feat/plugin-debug` together with the Notion code removal (#1658). The pin, - * `bae5cdbe3`, has both. This spec + * The connect flow is the proxy's 0.2 one (#54 phase 2): the page redeems the + * handoff signed with the user's key and delegates the connection to the + * app's agent; the frame calls the proxy itself with a capability and its + * own key (atomic-server#1697, in the pin). This spec * replaces the old one, which drove the `[data-integration=notion]` card that * atomic-server 4bab16ee6 removed (#68). Its two-way, PATCH and * revoked-access checks have no read-only counterpart, so they are gone. @@ -35,7 +35,7 @@ test.describe('notion drive plugin', () => { // No integration-discovery settings: a drive app needs none, and that // helper's signature differs between the pinned and newer atomic-server. - test('imports every shared Notion page through the proxy relay', async ({ + test('imports every shared Notion page through the integration proxy', async ({ page, }) => { test.skip( @@ -64,11 +64,11 @@ test.describe('notion drive plugin', () => { ).toBeVisible(); await page .getByRole('button', { - name: 'Use LocalThought to sync Notion with your Atomic Data Hub', + name: 'Use LocalThought to sync Notion with this destination', exact: true, }) .click(); - await expect(page).not.toHaveURL(/connection_code=/); + await expect(page).not.toHaveURL(/connection_code=|integration_state=/); // Back on the app, which finds its connection and imports on open. await expect( diff --git a/integrations/pets/e2e/pets.spec.ts b/integrations/pets/e2e/pets.spec.ts index 16e83117f..a37b6074c 100644 --- a/integrations/pets/e2e/pets.spec.ts +++ b/integrations/pets/e2e/pets.spec.ts @@ -4,17 +4,26 @@ * discover it on the Integrations page, install it (the host downloads the * module the catalog entry names and checks it against the entry's integrity * hash), connect Pets through the host's consent bar and the (mock) - * integration proxy, import the five pets through the host's proxy relay into - * the app's own table, and reopen it. Then move it to the catalog's version - * from an older one, keeping its rows. No credential ever reaches the frame or - * the drive, and no test helper touches the app's source. + * integration proxy, import the five pets into the app's own table, and + * reopen it. Then move it to the catalog's version from an older one, keeping + * its rows. No credential ever reaches the frame or the drive, and no test + * helper touches the app's source. + * + * The connect flow is the integration proxy's 0.2 one (#54 phase 2): consent + * bar → proxy `/connect` → back to `/app/integrations`, where the page + * redeems the handoff signed with the user's key (the user owns the + * connection) and delegates it to the app's agent; the frame then gets a + * capability from the page and calls the proxy itself, signing each request + * with its own key. The mock proxy checks every signature the way the real + * one does. Revoking the delegation and picking "Use existing connection" + * gets the app back without a second trip through the proxy. * * The lane's dev-server stands in for GitHub Pages: it serves the committed * `apps/pets//ui.js` at `/apps/pets//ui.js` and points the * catalog's `app-module` there, leaving `app-module-integrity` as committed * (integrations/tooling/apps.mjs). * - * Needs an atomic-server with the host proxy relay (atomic-server#1657) and + * Needs an atomic-server with frame capabilities (atomic-server#1697) and * catalog app installation (atomic-server#1689, for #94). Run it the way CI * does: * node integrations/tooling/run-lane.mjs pets --tier e2e @@ -23,7 +32,7 @@ import { test, expect, type Page } from '@playwright/test'; import { before } from '../../../browser/e2e/tests/test-utils'; /** The catalog's version of the Pets app (integrations/catalog.json). */ -const VERSION = '0.1.0'; +const VERSION = '0.1.1'; test.describe('pets integration', () => { test.beforeEach(before); @@ -66,7 +75,7 @@ test.describe('pets integration', () => { ).toBeVisible(); await page .getByRole('button', { - name: 'Use LocalThought to sync Pets with your Atomic Data Hub', + name: 'Use LocalThought to sync Pets with this destination', exact: true, }) .click(); @@ -77,16 +86,45 @@ test.describe('pets integration', () => { app.getByRole('status').filter({ hasText: 'Last synced' }), ).toContainText('5 pets (5 added', { timeout: 30_000 }); - // The frame never saw the rotating code; the page keeps it, and nothing - // in the drive does. - const stored = await page.evaluate(() => - Object.keys(localStorage).filter(k => - k.startsWith('atomic-proxy-connection-v1:'), - ), + // The connection lives at the proxy, owned by the signed-in user and + // delegated to this app. The page keeps nothing credential-like: not + // even the PKCE state of the finished handoff. + const [connection] = await proxyConnections('pets'); + expect(connection.owner).toBe(await signedInAgent(page)); + expect(connection.delegations).toHaveLength(1); + expect(connection.last_used_at).not.toBeNull(); + expect(await page.evaluate(() => Object.keys(localStorage))).not.toEqual( + expect.arrayContaining([ + expect.stringMatching(/^atomic-proxy-connect|connection-v1/), + ]), ); - expect(stored).toHaveLength(1); const table = await tableOf(page); + // Revoked at the proxy (say, from another device): the app is no longer + // connected. Using the existing connection again delegates it anew, + // with no trip through the proxy's consent page. + await revoke(connection.connection_id, connection.delegations[0].agent); + await page.reload(); + await expect(app.getByRole('status')).toContainText('Not connected', { + timeout: 30_000, + }); + await app.getByRole('button', { name: 'Connect Pets' }).click(); + await consent + .getByRole('button', { name: 'Use existing connection' }) + .click(); + await expect(consent).toBeHidden(); + await expect( + app.getByRole('status').filter({ hasText: 'Last synced' }), + ).toContainText('5 pets (0 added, 0 updated, 5 unchanged)', { + timeout: 30_000, + }); + expect(page.url()).toBe(appUrl); + const again = await proxyConnections('pets'); + expect(again).toHaveLength(1); + expect(again[0].delegations.map(d => d.agent)).toEqual( + connection.delegations.map(d => d.agent), + ); + // Reopen from the catalog card: installed at the catalog's version, still // connected, and a re-sync finds nothing new. const reopened = await openCatalogCard(page); @@ -163,6 +201,47 @@ test.describe('pets integration', () => { }); }); +interface MockConnection { + connection_id: string; + platform: string; + owner: string; + last_used_at: string | null; + delegations: { agent: string; label: string | null }[]; +} + +/** The mock proxy's connections for `platform` (test-side introspection). */ +async function proxyConnections(platform: string): Promise { + const response = await fetch( + `${process.env.INTEGRATION_PROXY_URL}/__mock/connections`, + ); + const { connections } = (await response.json()) as { + connections: MockConnection[]; + }; + + return connections.filter(c => c.platform === platform); +} + +/** Drops one delegation at the mock proxy, as the owner would elsewhere. */ +async function revoke(connectionId: string, agent: string) { + const response = await fetch( + `${process.env.INTEGRATION_PROXY_URL}/__mock/revoke`, + { + method: 'POST', + body: JSON.stringify({ connection_id: connectionId, agent }), + }, + ); + expect(response.status).toBe(200); +} + +/** The signed-in agent as the proxy names it: `atomic:agent:`. */ +async function signedInAgent(page: Page): Promise { + const key = await page.evaluate(() => + window.store!.getAgent()!.getPublicKey(), + ); + + return `atomic:agent:${Buffer.from(key, 'base64').toString('base64url')}`; +} + /** The Integrations page's Pets card, with experimental plugins shown. */ async function openCatalogCard(page: Page) { await page.goto(new URL('/app/integrations', page.url()).href); diff --git a/integrations/timesheets/e2e/clockify.spec.ts b/integrations/timesheets/e2e/clockify.spec.ts index 570387ef9..40f771c6f 100644 --- a/integrations/timesheets/e2e/clockify.spec.ts +++ b/integrations/timesheets/e2e/clockify.spec.ts @@ -4,7 +4,7 @@ * end in a real host: the app runs in its null-origin iframe, connects * Clockify through the host's consent bar and the (mock) integration proxy, * is set up in the frame (workspace, account, 7/30-day look-back), and - * imports through the host's proxy relay into its own table, with the + * imports through the integration proxy into its own table, with the * Properties it creates under its own ontology. Then: reload (no * duplicates), a changed entry, a wider window, and a proxy failure that * leaves the rows readable and recovers. @@ -90,15 +90,15 @@ test.describe('timesheets drive app', () => { await expect( page.getByRole('heading', { name: 'Mock integration proxy' }), ).toBeVisible(); + // An API-key platform: the key is pasted on the proxy's own page and + // stays there, sealed in the connection; the drive never sees it. + await page.getByLabel('API key').fill('synthetic-clockify-key'); await page - .getByRole('button', { - name: 'Use LocalThought to sync Clockify with your Atomic Data Hub', - exact: true, - }) + .getByRole('button', { name: 'Connect Clockify', exact: true }) .click(); await expect(page).not.toHaveURL(/connection_code=|integration_state=/); - // Setup, in the frame: the account and its workspaces come through the relay. + // Setup, in the frame: the account and its workspaces come through the proxy. await expect(status).toContainText('Choose the workspace', { timeout: 30_000, }); @@ -120,14 +120,18 @@ test.describe('timesheets drive app', () => { ); const table = await tableOf(page); - // The drive holds settings, never the connection: the page keeps the - // rotating code in its own storage, bound to this app. - const stored = await page.evaluate(() => - Object.keys(localStorage).filter(k => - k.startsWith('atomic-proxy-connection-v1:'), - ), + // The drive holds settings, never the connection or the key. + // The connection lives at the proxy, owned by the signed-in user and + // delegated to this app; the page keeps nothing credential-like. + const connections = await proxyConnections('clockify'); + expect(connections).toHaveLength(1); + expect(connections[0].owner).toBe(await signedInAgent(page)); + expect(connections[0].delegations).toHaveLength(1); + expect(await page.evaluate(() => Object.keys(localStorage))).not.toEqual( + expect.arrayContaining([ + expect.stringMatching(/^atomic-proxy-connect|connection-v1/), + ]), ); - expect(stored).toHaveLength(1); const appValues = await page.evaluate(async () => { const store = window.store!; const subject = new URL(location.href).searchParams.get('subject')!; @@ -135,7 +139,9 @@ test.describe('timesheets drive app', () => { return JSON.stringify((await store.getResource(subject)).getPropVals()); }); expect(appValues).toContain('aaaaaaaaaaaaaaaaaaaaaaaa'); - expect(appValues).not.toMatch(/connection[-_]?code|bearer/i); + expect(appValues).not.toMatch( + /connection[-_]?code|bearer|capabilit|synthetic-clockify-key/i, + ); // Columns are Properties the app created, with Atomic datatypes. expect(await columnDatatypes(page, table)).toMatchObject({ @@ -252,6 +258,34 @@ async function columnDatatypes( }, table); } +interface MockConnection { + connection_id: string; + platform: string; + owner: string; + delegations: { agent: string; label: string | null }[]; +} + +/** The mock proxy's connections for `platform` (test-side introspection). */ +async function proxyConnections(platform: string): Promise { + const response = await fetch( + `${process.env.INTEGRATION_PROXY_URL}/__mock/connections`, + ); + const { connections } = (await response.json()) as { + connections: MockConnection[]; + }; + + return connections.filter(c => c.platform === platform); +} + +/** The signed-in agent as the proxy names it: `atomic:agent:`. */ +async function signedInAgent(page: Page): Promise { + const key = await page.evaluate(() => + window.store!.getAgent()!.getPublicKey(), + ); + + return `atomic:agent:${Buffer.from(key, 'base64').toString('base64url')}`; +} + /** The app's table: the value on the app that is a Table (`app-data`). */ async function tableOf(page: Page): Promise { return page.evaluate(async () => { diff --git a/integrations/tooling/run-lane.mjs b/integrations/tooling/run-lane.mjs index 90f57f9bf..4a8de3de8 100644 --- a/integrations/tooling/run-lane.mjs +++ b/integrations/tooling/run-lane.mjs @@ -22,7 +22,7 @@ import { spawnSync } from 'node:child_process'; import { existsSync, symlinkSync } from 'node:fs'; import { resolve } from 'node:path'; import { loadLanes, lanePorts, root, TIERS } from './lanes.mjs'; -import { bringUp } from './serve.mjs'; +import { bringUp, mockProxyOrigin } from './serve.mjs'; import { layoutProblems } from './link-atomic-server.mjs'; // A warning, not a failure: testing against another atomic-server commit on @@ -196,7 +196,7 @@ for (const tier of order.filter(t => tiers.includes(t))) { SERVER_URL: `http://localhost:${ports.atomicServer}`, FRONTEND_URL: `http://localhost:${ports.atomicServer}`, PLUGIN_CATALOG_URL: `http://localhost:${ports.devServer}/integrations/catalog.json`, - INTEGRATION_PROXY_URL: `http://127.0.0.1:${ports.mockProxy}`, + INTEGRATION_PROXY_URL: mockProxyOrigin(ports), ATOMIC_MOCK_INTEGRATION_PROXY: '1', }, ); diff --git a/integrations/tooling/serve.mjs b/integrations/tooling/serve.mjs index 3fa73e372..551db47c4 100644 --- a/integrations/tooling/serve.mjs +++ b/integrations/tooling/serve.mjs @@ -51,17 +51,28 @@ export function serverEnv(ports, store) { ATOMIC_PORT: String(ports.atomicServer), ATOMIC_DOMAIN: 'localhost', ATOMIC_REPOPULATE_DEFAULTS: 'true', - // Mirrors what atomic-server's own dagger e2e pipeline sets for parity; - // nothing in server/src reads these today, so they are a no-op kept only - // so this matches upstream if a future commit does. (In a container, - // 127.0.0.1 would be the container itself. Revisit that if one starts - // being read. Plugin ctx.http refuses loopback addresses anyway.) - ATOMIC_INTEGRATION_PROXY_URL: `http://127.0.0.1:${ports.mockProxy}`, + // `--integration-proxy-url` (atomic-server#1702): the proxy origin whose + // `ctx.http` requests the host signs with the installation's node agent, + // and the one loopback origin let through the public-address check. It + // must equal the mock's MOCK_PROXY_BASE_URL, which every signature + // covers. No plugin in this repo reaches the proxy with `ctx.http` yet + // (README, "Sandbox plugins and the proxy"), so no lane exercises it. + // In a container (ATOMIC_SERVER_IMAGE), 127.0.0.1 is the container + // itself; revisit when a lane needs server-side proxy calls. + ATOMIC_INTEGRATION_PROXY_URL: mockProxyOrigin(ports), + // Mirrors atomic-server's own dagger e2e pipeline; nothing in server/src + // reads it today. ATOMIC_INTEGRATION_FRONTEND_ORIGIN: `http://localhost:${ports.atomicServer}`, - TENANT_SECRET: 'bW9jay10ZW5hbnQ.mock-signature', }; } +/** + * The mock proxy's public origin (its BASE_URL): what the browser is told + * (INTEGRATION_PROXY_URL in run-lane.mjs), what the server is told, and what + * every v2 signature and capability `aud` must name, byte for byte. + */ +export const mockProxyOrigin = ports => `http://127.0.0.1:${ports.mockProxy}`; + /** Where the image keeps its store (the Dockerfile's VOLUME). */ export const IMAGE_STORE = '/data'; @@ -268,6 +279,7 @@ export async function bringUp({ ports, platforms, label = 'shared' }) { // SPA from — atomic-server directly (FRONTEND_URL in run-lane.mjs and // ci.yml), not the dev-server, which only hosts the catalog. The mock proxy // rejects any /connect whose redirect_uri has another origin. + // MOCK_PROXY_BASE_URL is the origin clients sign for (mockProxyOrigin). const mock = platforms === undefined || platforms.length > 0; if (mock) start( @@ -276,6 +288,7 @@ export async function bringUp({ ports, platforms, label = 'shared' }) { ['integrations/localthought/mock-proxy.mjs'], { MOCK_PROXY_PORT: String(ports.mockProxy), + MOCK_PROXY_BASE_URL: mockProxyOrigin(ports), MOCK_FRONTEND_ORIGIN: `http://localhost:${ports.atomicServer}`, MOCK_PROXY_PLATFORMS: (platforms ?? []).join(','), }, From 01c6467885c9cd50dfeac9f4077e5faa8f440912 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 24 Sep 2026 17:13:06 +0200 Subject: [PATCH 7/8] docs: the #54 phase 2 client flow, the 0.2 mock proxy, and what was deleted - integrations/README.md: "The host's proxy access" replaces "The host relay" (connections at the proxy, delegations, "Use existing connection", frame key + capability + v2 signatures, proxy refusals, the new no-credentials rules); new "Sandbox plugins and the proxy": the pin has proxy: [...] / atomic-proxy: and host signing, but no plugin here uses it yet (they call providers with secrets; POST /runtimes from the page is still to do upstream). - localthought/README.md: now describes the mock proxy (routes, checks, signed origin, test-side routes, what it lacks) and lists what #54 phase 2 deleted; the retired runtime stays as history. - READINESS, PARALLEL_LANES, plugin READMEs, the root README and AGENTS.md: no relay or rotating codes; the pin requirement is #1697. - integration-proxy/SELF_HOSTING.md: what the data browser does on Connect (redeem signed, delegation, frame calls with a capability; CORS for the data browser's origin and Origin: null); the not-verified note no longer points at the deleted browser.ts. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 21 ++- README.md | 10 +- integration-proxy/SELF_HOSTING.md | 28 +++- integrations/PARALLEL_LANES.md | 22 +-- integrations/READINESS.md | 20 ++- integrations/README.md | 101 +++++++++--- integrations/calendar/README.md | 22 +-- integrations/issue-tracker/README.md | 9 +- integrations/localthought/README.md | 230 +++++++++++---------------- integrations/notion/README.md | 9 +- integrations/pets/README.md | 30 ++-- integrations/timesheets/README.md | 24 +-- 12 files changed, 290 insertions(+), 236 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b28aa8424..525f18f7e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,9 +58,13 @@ in [`integrations/READINESS.md`](integrations/READINESS.md). provider integrations. One ES module built by `app/build.mjs` that exports `view({ root, store })`. atomic-server runs it as an App's entry point in a null-origin iframe (`sandbox="allow-scripts allow-modals"`). - It never holds a credential: every provider call goes through the host relay - `store.proxy.request`/`.connections`/`.connect` (ontola/atomic-server#1657), - and the top page holds the integration-proxy connection. Reading uses + It never holds a credential: every provider call goes through + `store.proxy.request`/`.connections`/`.connect`. Since #54 phase 2 + (ontola/atomic-server#1697) the connection lives at the integration + proxy, owned by the user's agent and delegated to the app's; the frame + calls the proxy itself with a short-lived capability from the page and a + key only it holds (`integrations/README.md`, "The host's proxy + access"). Reading uses the npm `syncables/browser` package where an OpenAPI document drives the paging, and optionally a lens from the npm `devonian` package for the mapping. `pets/app/` (syncables), `notion/app/` (syncables plus a @@ -81,8 +85,8 @@ in [`integrations/READINESS.md`](integrations/READINESS.md). 3. **Unhosted libraries** — mapping code, Devonian lenses and bridges with no runtime of their own: `calendar/adapter.ts` and `calendar/devonian/google-calendar/`, `issue-tracker/todoist.ts`, the - GitHub issues lens and bridge in `issue-tracker/devonian/github-issues/`, - and `BrowserIntegrations` (`localthought/browser.ts`). Their former + and the GitHub issues lens and bridge in + `issue-tracker/devonian/github-issues/`. Their former hosts in atomic-server's data-browser (the LocalThought connect dialog and sync panel, the Devonian demo) were removed; the data-browser no longer imports anything from `integrations/`. A library reaches users @@ -165,9 +169,10 @@ has been removed from this repo entirely — `atomic-server`'s WASM build depends on it, so it belongs there, not here. See the "Building a LocalThought" section of [`integrations/README.md`](integrations/README.md#building-a-localthought-reflectorsyncablesdevonian-connector) -for the fuller architecture note, and the `describeIntegration`/ -`fetchIntegration` machinery that depended on it, likewise removed from -[`integrations/localthought/browser.ts`](integrations/localthought/browser.ts). +for the fuller architecture note. The `describeIntegration`/ +`fetchIntegration` machinery that depended on it was removed from +`integrations/localthought/browser.ts`, and that file itself was deleted in +#54 phase 2 with the proxy's rotating connection codes. ## overlays/ diff --git a/README.md b/README.md index 2c75b5d4c..68817860d 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ deprecated. `localthought/overlays` repo with its history intact, and published by GitHub Pages at https://ontola.github.io/atomic-plugins/overlays/. - `integration-proxy/` — the Rust OAuth/API proxy (LocalThought) that drive - apps reach through atomic-server's host relay. See its own + apps reach through atomic-server's `store.proxy`. See its own [README](integration-proxy/README.md) and [AGENTS.md](integration-proxy/AGENTS.md). To run your own instance instead of atomic.place's, see [integration-proxy/SELF_HOSTING.md](integration-proxy/SELF_HOSTING.md). @@ -37,7 +37,7 @@ pinned atomic-server (`.atomic-server-ref`, `bae5cdbe3`), its scope, and which evidence is unit, host E2E, live or historical. In short, at that pin: the Pets and Notion drive apps import through the -host's integration-proxy relay and pass a host E2E against a mock proxy, but +host's `store.proxy` and pass a host E2E against a mock proxy, but no host UI installs them from the catalog yet ([#94](https://github.com/ontola/atomic-plugins/issues/94)). Bank statements is set up and fed files through the host's generic file entry point, after a @@ -52,11 +52,11 @@ Screenshots are tracked in | Plugin | What it does (catalog copy) | Current runtime | Code | Blocker | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 🐾 **Pets** | A trivial demo: imports five static pets into a Pets table. No account or network call. | Drive app over the host relay (read from a mock `pets` platform); the static no-network demo is a separate sandbox bundle | [`integrations/pets/`](integrations/pets/) | [#94](https://github.com/ontola/atomic-plugins/issues/94) | -| 📓 **Notion** | Sync supported row fields, property names and table or board views of a Notion database. Hidden (`enabled: false`). | Read-only drive app over the host relay; the two-way sandbox pilot has no host UI | [`integrations/notion/`](integrations/notion/) | [#94](https://github.com/ontola/atomic-plugins/issues/94), [#97](https://github.com/ontola/atomic-plugins/issues/97), [#8](https://github.com/ontola/atomic-plugins/issues/8) | +| 🐾 **Pets** | A trivial demo: imports five static pets into a Pets table. No account or network call. | Drive app over `store.proxy` (read from a mock `pets` platform); the static no-network demo is a separate sandbox bundle | [`integrations/pets/`](integrations/pets/) | [#94](https://github.com/ontola/atomic-plugins/issues/94) | +| 📓 **Notion** | Sync supported row fields, property names and table or board views of a Notion database. Hidden (`enabled: false`). | Read-only drive app over `store.proxy`; the two-way sandbox pilot has no host UI | [`integrations/notion/`](integrations/notion/) | [#94](https://github.com/ontola/atomic-plugins/issues/94), [#97](https://github.com/ontola/atomic-plugins/issues/97), [#8](https://github.com/ontola/atomic-plugins/issues/8) | | ⏱️ **Clockify** | Bring completed Clockify time entries (past 7 or 30 days) into a Time Tracker. Import only. | Drive app, no connect/setup step yet | [`integrations/timesheets/`](integrations/timesheets/) | [#96](https://github.com/ontola/atomic-plugins/issues/96) | | 🏦 **Bank statements** | Import bank transactions from MT940 and camt.053 statement exports; up to 500 transactions per file. No bank token. | Sandbox bundle, started from the host's generic file entry point (atomic-server#1653, in the pin); host E2E on synthetic statements | [`integrations/money/`](integrations/money/) | [#94](https://github.com/ontola/atomic-plugins/issues/94) (publication) | -| 🗓️ **Google Calendar** | Import one Google calendar's single (non-recurring) events into a table, and send reviewed edits of five fields back with `If-Match`. | Drive app over the host relay; mock-tested in a host e2e, not live-verified | [`integrations/calendar/`](integrations/calendar/) | [#94](https://github.com/ontola/atomic-plugins/issues/94) (install), live verification ([#101](https://github.com/ontola/atomic-plugins/issues/101)) | +| 🗓️ **Google Calendar** | Import one Google calendar's single (non-recurring) events into a table, and send reviewed edits of five fields back with `If-Match`. | Drive app over `store.proxy`; mock-tested in a host e2e, not live-verified | [`integrations/calendar/`](integrations/calendar/) | [#94](https://github.com/ontola/atomic-plugins/issues/94) (install), live verification ([#101](https://github.com/ontola/atomic-plugins/issues/101)) | | ✅ **Todoist** (Devonian) | Bring Todoist projects and active tasks into a local issue tracker. Read only. | Projection library, no host | [`integrations/issue-tracker/`](integrations/issue-tracker/) | [#99](https://github.com/ontola/atomic-plugins/issues/99) | | 🐙 **GitHub issues** (Devonian lens) | Maps GitHub issues and comments to and from Atomic issue-tracker resources. No catalog card. | Lens and bridge libraries, no host since atomic-server#1612 | [`integrations/issue-tracker/devonian/github-issues/`](integrations/issue-tracker/devonian/github-issues/) | [#100](https://github.com/ontola/atomic-plugins/issues/100) | | 🐦 **Moneybird** | Import a Moneybird administration's bookkeeping records into typed tables. Read only. | Catalog entry and overlay only; no package here | — | [#102](https://github.com/ontola/atomic-plugins/issues/102) | diff --git a/integration-proxy/SELF_HOSTING.md b/integration-proxy/SELF_HOSTING.md index 81cc2a15f..ee34b96ca 100644 --- a/integration-proxy/SELF_HOSTING.md +++ b/integration-proxy/SELF_HOSTING.md @@ -515,6 +515,22 @@ that is live); builds at the time of writing fall back to `VITE_INTEGRATION_PROXY_URL=https://proxy.example.org` to make your proxy the default for everyone who uses that build. +What the data browser does with it, when a user clicks *Connect* for a +drive app (atomic-server#1697): it sends the whole tab to the proxy's +`/connect` (no login, no `user_id`); the proxy's page shows the platform and +the data browser's origin, and goes to the provider (or asks for the API +key); the proxy returns the tab to the data browser's `/app/integrations` +with a single-use handoff code. The data browser then redeems it at `POST +/connect/redeem`, signed with the user's Atomic key, which makes the user +the connection's owner, and delegates the connection to the app's agent +(`POST /connections/{id}/agents`). From then on, the app's null-origin frame +calls `/proxy/{connection_id}/{platform}/…` on your proxy directly, with a +capability the data browser signed and a key only the frame holds. Your +proxy therefore has to answer CORS for the data browser's origin and for +`Origin: null`; it does, for any origin and without cookies. If a user +already has a connection for that platform, the data browser offers to +reuse it, which only adds a delegation. + Connections are stored in the proxy that created them. Pointing Atomic at a different proxy does not move them: users connect again on the new one. @@ -626,11 +642,13 @@ needs: - The Atomic Server option (atomic-server#1702) was unmerged when this was written. The data-browser setting was described from the atomic-server source on its `feat/plugin-debug` branch - (`browser/data-browser/src/components/Settings/IntegrationSettings.tsx`, - `browser/data-browser/src/helpers/integrationProxy.ts`, and this - repository's - [`integrations/localthought/browser.ts`](../integrations/localthought/browser.ts) - for the fallback default), not from a release. + (`browser/data-browser/src/components/Settings/IntegrationSettings.tsx` + and `browser/data-browser/src/helpers/integrationProxy.ts`), not from a + release. The connect flow above was read from atomic-server#1697 and run + against this repository's mock proxy + (`integrations/localthought/mock-proxy.mjs`, which re-implements the + proxy's signature, capability and delegation checks) in the drive apps' + e2e tests, not against a running `integration-proxy`. Questions and corrections: [ontola/atomic-plugins issues](https://github.com/ontola/atomic-plugins/issues). diff --git a/integrations/PARALLEL_LANES.md b/integrations/PARALLEL_LANES.md index 9497aad39..575dec6c2 100644 --- a/integrations/PARALLEL_LANES.md +++ b/integrations/PARALLEL_LANES.md @@ -307,9 +307,11 @@ integrations/tooling/fixtures/ ``` - `mock-proxy.mjs` keeps ownership of the parts that are _protocol_, not - platform: PKCE, `/connect`, `/connect/redeem`, single-use connection codes, - `X-Connection-Code` rotation, `redirect_uri` origin validation. Those are - already correct and should not be duplicated per platform. + platform: the integration proxy's 0.2 flow (#54 phase 2) — PKCE, + `/connect`, `/connect/redeem` signed by the owner, connections, + delegations and runtimes, v2 request signatures, frame capabilities — + and `redirect_uri` origin validation (`localthought/README.md`). Those + should not be duplicated per platform. - `MOCK_PROXY_PLATFORMS=github-issues,todoist` restricts which fixtures load, so `/catalog` returns exactly that lane's platforms. - **"Realistic" has to be enforced, not asserted.** `record.mjs` writes `api/` @@ -392,16 +394,16 @@ Rules that keep parallel worktrees from fighting: - **Quarantined e2e.** None of the lane e2e tiers are held back any more. `pets` (#52) and `notion` (#68) are back: both drive their drive app in its - plugin iframe through the host proxy relay (store.proxy), so they need an - `.atomic-server-ref` that contains ontola/atomic-server#1657 (#1624's host - relay). The pin does: it is `bae5cdbe3`, the head of atomic-server's - `feat/plugin-debug` after #1657 and #1658 (the Notion code removal) were - merged there, no longer a PR head. The `e2e-plugin-system` job is required - again since #71. + plugin iframe through `store.proxy`, which since #54 phase 2 needs an + `.atomic-server-ref` with frame capabilities (ontola/atomic-server#1697) + and the v2 request signatures (#1696): the mock proxy refuses the older + relay's rotating connection codes. The pin, `11264e83e` on + `claude/atomic-plugins-pin-phase2`, has both. The `e2e-plugin-system` job + is required again since #71. - **`timesheets`' e2e is new, not moved.** The upstream Clockify tests were deleted in atomic-server `4bab16ee6` (in the pin), together with the UI they drove (#44). `integrations/timesheets/e2e/clockify.spec.ts` (#96) - drives the timesheets drive app through the host relay instead, with a + drives the timesheets drive app through `store.proxy` instead, with a test-side install until #94. See [`HANDOFF-e2e-split.md`](HANDOFF-e2e-split.md). - `integrations/money/` has one tier, `e2e` (#95): `money.spec.ts` drives diff --git a/integrations/READINESS.md b/integrations/READINESS.md index d13ccc66e..d95f7c257 100644 --- a/integrations/READINESS.md +++ b/integrations/READINESS.md @@ -34,9 +34,12 @@ read from the atomic-server source at the pin. rendered (`pluginCatalog.ts`, `IntegrationStore.tsx`). - **Drive apps.** `New app` creates an App whose entry point's source can be replaced. The app's view runs in a null-origin iframe. It reaches the - integration proxy only through the host relay, `store.proxy.request`, - `.connections` and `.connect` (ontola/atomic-server#1657). The top page - holds the connection and draws the consent bar. No UI installs a drive + integration proxy only through `store.proxy.request`, `.connections` + and `.connect`. Since #54 phase 2 (ontola/atomic-server#1697, in the pin) + the connection lives at the proxy, owned by the user's agent and + delegated to the app's; the top page draws the consent bar (with "Use + existing connection" when there is one), and the frame calls the proxy + itself with a capability from the page and its own key. No UI installs a drive app from the catalog; the E2Es below install test-side ([#94](https://github.com/ontola/atomic-plugins/issues/94)). - **Sandbox plugins.** The QuickJS/WASM runtime is present @@ -57,9 +60,9 @@ read from the atomic-server source at the pin. | Plugin (catalog id) | Runtime of the current code | Install entry point at the pin | Import / write scope (declared) | Evidence | Open blockers | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Pets, drive app (`pets`) | Drive app `pets/app/`: iframe, `syncables/browser` over the host relay | None in UI. Host E2E installs test-side (`setAppSource`) | Read-only. Pets from the mock `pets` platform into the app's own table | Unit; **Host E2E** (`pets` lane: connect, 5 rows, datatypes) | [#94](https://github.com/ontola/atomic-plugins/issues/94) install from catalog | +| Pets, drive app (`pets`) | Drive app `pets/app/`: iframe, `syncables/browser` over `store.proxy` | None in UI. Host E2E installs test-side (`setAppSource`) | Read-only. Pets from the mock `pets` platform into the app's own table | Unit; **Host E2E** (`pets` lane: connect, 5 rows, datatypes) | [#94](https://github.com/ontola/atomic-plugins/issues/94) install from catalog | | Pets, static demo (`pets`) | Sandbox `pets/plugin.js`, no network | None. Its setup dialog was removed in `4bab16ee6` | Five static pets into a Pets table | Unit; `certify.mjs --layer js`. Historical: Rust sandbox test (removed from atomic-server in `4bab16ee6`) | None filed; the catalog card still describes this demo, not the drive app | -| Notion, drive app (`notion`, `enabled: false`) | Drive app `notion/app/`: iframe, `syncables/browser` + Devonian `AtomicLens` over the relay | None in UI. Host E2E installs test-side | Read-only. Every shared data source into one table; plain fields only | Unit; **Host E2E** (`notion` lane: connect, 3 rows, column datatypes, formatted-text warning). No live run | [#94](https://github.com/ontola/atomic-plugins/issues/94), [#97](https://github.com/ontola/atomic-plugins/issues/97) local edits, [#8](https://github.com/ontola/atomic-plugins/issues/8) write | +| Notion, drive app (`notion`, `enabled: false`) | Drive app `notion/app/`: iframe, `syncables/browser` + Devonian `AtomicLens` over `store.proxy` | None in UI. Host E2E installs test-side | Read-only. Every shared data source into one table; plain fields only | Unit; **Host E2E** (`notion` lane: connect, 3 rows, column datatypes, formatted-text warning). No live run | [#94](https://github.com/ontola/atomic-plugins/issues/94), [#97](https://github.com/ontola/atomic-plugins/issues/97) local edits, [#8](https://github.com/ontola/atomic-plugins/issues/8) write | | Notion, two-way pilot (`notion`) | Sandbox `notion/plugin.js` | None. `ConnectNotion` was removed in `4bab16ee6` | Two-way on one data source: plain fields, property names, table/board view subset (`package.json` capabilities) | Unit; `certify.mjs --layer js`; `live` tier runs the installer against the pinned server with Notion stubbed. Historical: live UI import and title edits via `ConnectNotion` | Retire once a drive-app write bridge has live evidence ([#8](https://github.com/ontola/atomic-plugins/issues/8)) | | Clockify (`timesheets`) | Drive app `timesheets/app/`: iframe, own Clockify client over `store.proxy.request` | None. The app has no connect or setup step yet | Read-only. Completed entries, past 7 or 30 days | Unit (fake store) only. Historical: `clockify-import.spec.ts`, which drove the retired LocalThought extension flow | [#96](https://github.com/ontola/atomic-plugins/issues/96), [#94](https://github.com/ontola/atomic-plugins/issues/94), [#97](https://github.com/ontola/atomic-plugins/issues/97) | | Bank statements (`money`) | Sandbox `money/plugin.js`, file handed over as `ctx.upload`, no network | Draft from a published release (Integrations → Community plugins → Create draft), then Set up and Import on the plugin page (atomic-server#1653's `accepts`/`destination`, in the pin). Publishing the bundle to a server is manual (#94) | Import only. MT940 ≤ 512 KB, camt.053 ≤ 5 MB, ≤ 500 transactions | Unit; `certify.mjs --layer js`; host E2E `money/e2e/money.spec.ts` (synthetic MT940/camt.053: import, reload, reimport, local edit, conflict, refused files). Historical: a real 272-transaction bunq MT940 export through `ImportMT940` (2026-09-11) | [#94](https://github.com/ontola/atomic-plugins/issues/94) | @@ -70,9 +73,10 @@ read from the atomic-server source at the pin. | Moneybird (`moneybird`) | None: catalog entry and `overlays/moneybird.com/` only | None | Declared: read-only bookkeeping collections | None | [#102](https://github.com/ontola/atomic-plugins/issues/102) | `integrations/localthought/` is shared tooling, not a user-facing plugin: -the shared mock proxy every E2E lane uses (`mock-proxy.mjs`), a generic -sandbox mapper (`plugin.ts`) and `BrowserIntegrations` (`browser.ts`). -Nothing at the pin calls the last two. +the shared mock proxy every E2E lane uses (`mock-proxy.mjs`, which speaks +the integration proxy's 0.2 protocol and checks its signatures and +capabilities) and a generic sandbox mapper (`plugin.ts`) that nothing at the +pin calls. `BrowserIntegrations` (`browser.ts`) was deleted in #54 phase 2. ## Commands diff --git a/integrations/README.md b/integrations/README.md index f903a7914..30bd9af80 100644 --- a/integrations/README.md +++ b/integrations/README.md @@ -513,8 +513,9 @@ data-browser, built on `BrowserIntegrations` (`localthought/browser.ts`), with catalog `platform` entries, lens hooks and the generic sandbox mapper `localthought/plugin.ts`. atomic-server removed that flow (`f3efedf65`, `c707ca4ed`), and the data-browser no longer imports anything from this -repo. [`localthought/README.md`](localthought/README.md) still documents -it, as history. +repo. `browser.ts` and `settings.ts` spoke the proxy's rotating connection +codes, which #54 retired; they were deleted in #54 phase 2. +[`localthought/README.md`](localthought/README.md) says what is left. ### The stack, top to bottom @@ -522,29 +523,54 @@ it, as history. provider credentials (never the frame, the drive or AtomicServer), publishes a **catalog** of supported platforms, and serves each platform's OpenAPI document, already patched with the overlays it needs (see below). -- **The host relay** — atomic-server's top page holds the proxy connection - (a rotating connection code in its own `localStorage`, bound to the proxy - origin, drive, agent and app) and answers the frame's +- **The host's proxy access** (#54 phase 2; ontola/atomic-server#1696 + and #1697, in the pin). The proxy account is the user's Atomic agent. A + **connection** (platform + sealed provider token) lives at the proxy and + belongs to the agent that redeemed it; a **delegation** says "this app's + agent may use connection C". The app's frame keeps using `store.proxy.request({ platform, connectionId, path, method, query, body, ifMatch })` - with `{ status, headers, body }` only. `store.proxy.connections` lists the - app's connections, and `store.proxy.connect` asks the host to draw a - consent bar and start the PKCE handoff. This is - ontola/atomic-server#1657 (`helpers/proxyConnections.ts`, a port of - `localthought/browser.ts`), in the pin. It is an interim shape: #40/#54 - and atomic-server#1624 are meant to replace the rotating code with a - scoped capability without changing the apps. - **The connection code never reaches the frame or the graph.** Never - write it into an Atomic resource, not an App resource, config or row: a - resource syncs, its drive can be shared, and the proxy has no per-code - revocation ([#21](https://github.com/ontola/atomic-plugins/issues/21)). - `localthought/no-credentials-in-graph.test.mjs` (`node --test`, run by - CI's "Tooling unit tests" step) fails the build if any shipped source - under `integrations/` contains a `…/properties/…connection-code` URL, or - mentions `x-connection-code` outside `browser.ts`. It is a text scan, not - data-flow analysis. + and gets `{ status, headers, body }`; what changed is underneath: + - `store.proxy.connect({ platform })` draws the host's consent bar. If + the person already has a connection for the platform, the bar offers + "Use existing connection": the page delegates it to the app and + `connect` resolves `{ status: 'connected', connectionId, platform }`, + with no reload. Otherwise the page sends the tab to the proxy's + `/connect` (no login, no `user_id`), and back to `/app/integrations`, + where it redeems the handoff with a request signed by the user's key + (the signer becomes the owner) and delegates the connection to the + app's agent (`GET /app-agent`); the view reloads and `connect` never + settles. A cancel resolves `{ status: 'cancelled' }`. + - `store.proxy.connections({ platform })` lists the connections the + person delegated to this app, from the proxy's `GET /connections`. + - For `request`, view-client.js makes a non-extractable Ed25519 key in + the frame's memory, asks the page for a **capability** for it (signed + by the user's key after the page checked the delegation; at most + 10 minutes at the pin, 15 at the proxy), and calls + `{proxy}/proxy/{connection_id}/{platform}{path}` itself, with + `Authorization: Capability …` and an Atomic v2 request signature by the + frame key (method, full URL, timestamp, body hash). It mints a new + capability once on `401 capability_expired`. + - The proxy's own refusals come back as responses, `{ error, message }` + with an `integration-proxy/src/api_error.rs` code (`not_delegated`, + `unknown_connection`, …). Each app's transport throws them rather than + treating them as the provider's answer (`proxyRefusal` in + `pets/app/transport.ts` and its siblings); a lost delegation or a + deleted connection says "Connect again". + **Nothing credential-like reaches the frame's own code or the graph.** + The page's localStorage holds only a PKCE verifier for the ten minutes of + a handoff. Never write a connection code, capability or verifier into an + Atomic resource: a resource syncs and its drive can be shared + ([#21](https://github.com/ontola/atomic-plugins/issues/21)). + `localthought/no-credentials-in-graph.test.mjs` (`node --test`, run by + CI's "Tooling unit tests" step) fails the build if shipped source under + `integrations/` contains a property URL naming a connection code, + capability or code verifier, mentions the retired `x-connection-code` + header, or signs requests itself (`x-atomic-signature`, the capability + prefix): that is the host's job. It is a text scan, not data-flow + analysis. - **Syncables** — the npm `syncables` package, used in the frame as `syncables/browser` (`readPlatform`, `describePlatform`, a `Transport` - over the relay). It reads an OpenAPI document plus its + over `store.proxy.request`). It reads an OpenAPI document plus its [CRUD Causality Extension](https://github.com/pondersource/openapi-extensions/tree/main/spec/crud-causality) (`components.crudResources`) block, discovers the resource model and pages through it, so the app carries no provider-specific paging code. @@ -564,7 +590,8 @@ it, as history. ### Two shapes, pick one **(a) Read-only import.** Model it on `pets/app/`: a `transport.ts` that -turns syncables' requests into relay calls and refuses any URL outside the +turns syncables' requests into `store.proxy.request` calls, throws the +proxy's own refusals, and refuses any URL outside the document's `servers[0].url`; a `sync.ts` that creates one Property per field under the app's ontology, adds them to the row class's `recommends`, and upserts rows under the app's table keyed by a provider id; a `controller.ts` @@ -592,8 +619,32 @@ Give every native resource a stable identity independent of matching text title/body equality), journal writes before sending them (the provider side has no idempotent create, so an uncertain/lost response must stop rather than retry blindly), and treat a missing record as a conflict to resolve, -never an implicit deletion. The relay passes `method` and `ifMatch`, so -conditional `PATCH` requests are possible from a frame. +never an implicit deletion. `store.proxy.request` passes `method` and +`ifMatch`, so conditional `PATCH` requests are possible from a frame. A +thrown request (a lost response or a timeout) may have reached the +provider; a proxy refusal (`{ error }` with a proxy code) did not. + +### Sandbox plugins and the proxy + +A server-executed sandbox plugin (shape 1 in +[Plugin runtimes](../AGENTS.md#plugin-runtimes)) reaches the proxy with +`ctx.http`, not `store.proxy`. The pin has the host side +(ontola/atomic-server#1702, #1710, #1725): a manifest declares +`proxy: ["clockify"]`, its operations name `atomic-proxy:/clockify/` +URLs, and the host resolves one to +`{--integration-proxy-url}/proxy/{connection_id}/clockify/` for the +connection delegated to the installation (`ctx.connections`), signing it as +this node's agent for the installation. An `atomic-proxy:` request must +still match a declared operation. + +**No plugin in this repo uses it yet.** The calendar, issue-tracker and +Notion sandbox adapters call the provider directly with a plugin secret +(`secrets`), and moving them to proxy connections is #54 decision 11's +later step. It also needs the page to register a node's agent as a runtime +of the installation (`POST /runtimes`), which #1700 lists as still to do. +The mock proxy accepts runtime-signed requests (`POST /runtimes`, then a +request signed by the runtime agent), and `serve.mjs` passes the mock's +origin as `ATOMIC_INTEGRATION_PROXY_URL`, but no lane exercises that path. ### OpenAPI overlays and the pondersource extensions diff --git a/integrations/calendar/README.md b/integrations/calendar/README.md index b2bff9faf..cabbbbfc7 100644 --- a/integrations/calendar/README.md +++ b/integrations/calendar/README.md @@ -103,13 +103,16 @@ Declared, not live-verified (see _Verification_): `412` marks only that event "Changed in Google since this preview; not sent", and it is reviewed again after a refresh. The baseline advances only for events Google confirmed. -- **Uncertain writes.** The relay can throw after the host has dispatched a - write, for example when the response is lost. The page spends its rotating - connection code before dispatch, so neither side can know whether Google - applied the change. The app reports "Unknown whether Google applied it" and - stops sending the rest of the batch. It does not retry. The next refresh - asks to reconnect, and the preview after that shows what Google has: if the - change landed, the event simply agrees. +- **Uncertain writes.** `store.proxy.request` can throw after the frame + sent a write, for example when the response is lost, so the app cannot + know whether Google applied the change. It reports "Unknown whether Google + applied it" and stops sending the rest of the batch. It does not retry. + Since #54 phase 2 nothing is spent by a lost response (there are no + connection codes), so the next refresh works on the same connection and + shows what Google has: if the change landed, the event simply agrees. A + refusal by the proxy itself (`{ error }` with a proxy code, such as + `not_delegated`) was not sent to Google; the app says "Connect again" + when the connection is gone or no longer this app's. - **Notifications.** Writes use `sendUpdates=none` (`adapter.ts`, and the Devonian write-back in `devonian/google-calendar/sync.ts`), so guests are not emailed about edits made through the app. The review sheet says so; @@ -180,8 +183,9 @@ node --test integrations/localthought/mock-proxy.test.mjs - **Unit** (`app/sync.test.ts`, `adapter.test.ts`): the whole drive-app path against the stateful fixture in [`fixtures/google-calendar/scenario.mjs`](fixtures/google-calendar/scenario.mjs), - through a fake relay that behaves like the page's. That includes spending a - connection when a call throws. Covered: calendar list and selection; the + through a fake `store.proxy` that behaves like the host's frame client and + the proxy: a lost response spends nothing, a revoked delegation answers + `403 not_delegated`. Covered: calendar list and selection; the paged import with its page cap; all-day and timed rows; recurring and cancelled skips; refresh; review; `If-Match` on send; `412`; both-changed conflicts; a lost response followed by a reconnect; cancellation after diff --git a/integrations/issue-tracker/README.md b/integrations/issue-tracker/README.md index f752feee3..0b4543ff9 100644 --- a/integrations/issue-tracker/README.md +++ b/integrations/issue-tracker/README.md @@ -129,10 +129,13 @@ replace them. read in `hostStore.ts`, `proxyConnections.ts`, `collection.ts`; `app/frameStore.ts` has the detail): -- The rotating connection code never reaches the frame: the bridge's - `proxyTransport` runs with a `dispatch` over `store.proxy.request`, and its +- No credential reaches the app's code: the bridge's `proxyTransport` runs + with a `dispatch` over `store.proxy.request` (since #54 phase 2 the host's + frame client calls the proxy with a capability and its own key), and its write journal still guards uncertain writes. Host refusals that happen - before anything is sent are recognised by message and are not uncertain. + before anything is sent (no capability, no Ed25519 in this browser) are + recognised by message, and the proxy's own refusals by their `error` + code; neither is uncertain. - A resolved `save`/`newResource` is an acknowledged `/app-write` commit. - The frame's reads come from the host page's cache, which did **not** show the app's own save within 5 s in the e2e. The adapter corrects its reads diff --git a/integrations/localthought/README.md b/integrations/localthought/README.md index 4f137626c..80529d391 100644 --- a/integrations/localthought/README.md +++ b/integrations/localthought/README.md @@ -1,145 +1,101 @@ -# LocalThought browser integrations - -> **Historical.** Most of this file describes the LocalThought connect -> dialog, sync panel and lens hooks that atomic-server's data-browser used -> to have. atomic-server removed them (`f3efedf65`, `c707ca4ed`), and the -> pinned host (`.atomic-server-ref`) no longer imports anything from this -> folder; its relay (`helpers/proxyConnections.ts`) is a port of `browser.ts`. -> The UI steps, Settings, the Calendar and Todoist behaviour and the -> browser-only regression below refer to that retired runtime, and the -> verification notes were made against it. What this folder still provides -> is the shared mock proxy (`mock-proxy.mjs`) every e2e lane uses, and the -> `no-credentials-in-graph` check. Current provider integrations are drive -> apps; see -> [`../READINESS.md`](../READINESS.md). - -The LocalThought flow runs entirely in the browser: catalog discovery, OAuth -consent, PKCE-protected return handling, paginated Syncables reads, ontology -creation and local Store/OPFS writes. Installation validates access once, creates -a folder, and starts an automatic inbound import without a proposal dialog. No AtomicServer HTTP -instance is needed. LocalThought remains the remote OAuth and API proxy. -Of that, `BrowserIntegrations` (`browser.ts`, this directory) provides only -catalog discovery, OAuth/PKCE and the rotating-code authenticated proxy call -— see [Building a LocalThought connector](../README.md#building-a-localthought-reflectorsyncablesdevonian-connector) -in the parent README for exactly where that boundary sits. The paginated -Syncables read and ontology creation are done by a sync engine that -`atomic-server` composes on top of it; that engine's code does not live in -this repo. - -Open Integrations, select a platform and choose **Install and connect**. The -browser creates a PKCE verifier and opens LocalThought's consent page, where -the selected platform is shown before you approve access. OAuth returns to the -same frontend `/app/integrations` page, and the browser redeems the one-time -handoff with the verifier. No tenant secret is entered in the browser. The -short-lived return is bound to the agent, drive and proxy; its code is removed -from the address bar immediately. A ten-minute, non-secret session marker resumes -setup if removing those parameters remounts the page; completing installation or -closing its setup dialog clears the marker. -Connection codes are stored in this browser's localStorage, outside the synced -graph, and may be read by code running on this frontend origin. They must never -be written into an Atomic resource, including a drive plugin's own App resource -(ontola/atomic-plugins#21). `node --test -integrations/localthought/no-credentials-in-graph.test.mjs` enforces this for -shipped source under `integrations/`. Clearing site -data requires reconnecting. Existing server-held connections require reconnecting. -Web Locks serialize rotating codes across tabs; a request consumes its code -before dispatch and saves the replacement before processing data. Uncertain -requests cannot silently replay credentials. - -The pure import mapper produces the existing reviewed intents from what the -sync engine reads; user-edited plugin source is not executed on this path. -Local edits and repeated imports retain the existing reconciliation behavior. -(This paragraph used to describe a Rust `syncables` crate vendored under -`integrations/localthought/syncables/` and exposed to the browser via -`atomic-server`'s `wasm/src/integrations.rs` — that vendoring has been -removed from this repo; see the parent README's note on where the engine -now lives. The standalone TypeScript `syncables` package is unrelated and -lives at [`syncables/`](../../syncables/) in this repo's root.) - -## Installation and browser refresh - -After connecting, choose the scope and select **Complete installation**. The -browser checks one catalog-selected provider API URL (HTTP success and a JSON -response), without following pagination or saving that response. This is an -access check, not a guarantee that every collection can be imported. Catalog -metadata requests are separate from that one provider request. This access -check is performed by the sync engine `atomic-server` composes over -`BrowserIntegrations.request()`, not by anything in this repo. - -Installation immediately creates a normal folder and offers **Open folder**. -The full, paginated import runs in the background and creates typed tables and -views inside it. There is no JSON preview or Apply step for inbound records. -Opening the folder or a table refreshes it automatically, including after a -reload. While it remains open, a visible, online tab refreshes every five -minutes; returning to the tab or reconnecting the network also triggers refresh. -**Sync now** is available alongside **Syncing…**, the last successful sync time, -and any error. An import already started continues when navigating elsewhere -within the app. Closing the page stops it; reopening retries from the provider. - -Settings, connection identifiers and sync status are saved only in this browser, -scoped to the installing agent and drive. The folder and imported records are -normal Atomic data. Another browser can read those records but needs its own -connection to refresh them. No server runner or closed-tab schedule is created. -A Web Lock covers the whole fetch/map/apply cycle, so simultaneous folder opens -across tabs cannot independently import the same snapshot. - -Refresh uses the shared import baselines: stable source IDs reuse existing rows, -Atomic-only fields and local edits are preserved, and conflicts stop application -with a visible error. Missing rows do not imply deletion. Failed fetches leave -existing records readable and retain the last success time. A partial local -write is retried through the same stable identities on the next refresh. -Provider writes are still explicitly reviewed; opening a folder never sends -edits back to a provider. - -Existing manual installations remain readable. Completing installation with an -existing connection creates a new browser-refresh folder; it does not move or -silently take over the old plugin tables. - -## Build and proxy requirements - -- Build `atomic-wasm` using `cd browser/data-browser && pnpm build:wasm`. -- Open **Settings → Integration** to select the integration-proxy URL. The - preference is saved in this browser and applies without rebuilding. Connections - are isolated by proxy origin; switching back restores that proxy’s connections. - HTTPS or loopback HTTP origins only. **Reset to default** uses the deployment’s - `VITE_INTEGRATION_PROXY_URL`, or `https://localthought.io` when unset. -- Existing bundled GitHub, Notion and MT940 plugins remain available - independently. Clockify is a LocalThought lens (`integrations/timesheets/`). Proxy cards have an accent border and a “Via integration proxy” label. -- Deploy the companion integration-proxy CORS change. It handles preflights for - explicit Authorization headers and exposes `X-Connection-Code`, `Link`, - pagination/count headers, `ETag` and `Retry-After`. Cookie credentials are not - enabled; login and consent use top-level navigation. The browser sends - `platform`, `redirect_uri`, `user_id`, `code_challenge`, - `code_challenge_method=S256` and `credentials=connection` to `/connect`, then - redeems the callback code at `/connect/redeem` with its PKCE verifier. -- Native AtomicServer's `TENANT_SECRET`, `ATOMIC_INTEGRATION_PROXY_URL` and - `ATOMIC_INTEGRATION_FRONTEND_ORIGIN` no longer configure this flow. Its - `/integration-proxy/*` handlers and Syncables dependency have been removed. - -Consumer limits are 10,000 requests, 5,000 records, 10 MB per page/document -and 30 minutes per import, with a 30-second timeout per provider request. Calendar imports require explicit UTC date bounds. -Closed tabs do not run schedules. Other legacy integrations, -server plugin execution, actions and schedules are outside this migration. - -## Checks - -```sh -cargo check -p atomic-wasm --target wasm32-unknown-unknown -browser/node_modules/.bin/vitest run --config integrations/localthought/vitest.config.ts -``` - -For the browser-only mock journey (no AtomicServer on port 19999): +# LocalThought: the shared mock proxy and what is left of the old flow + +This folder holds: + +- **`mock-proxy.mjs`**, the local-only integration proxy every e2e lane + runs (`integrations/tooling/serve.mjs` starts it on the lane's + `mockProxy` port). Never deploy it. +- **`mock-proxy-auth.mjs`**, its copy of the real proxy's 0.2 + authentication checks, plus a test signer. +- **`no-credentials-in-graph.test.mjs`**, the text scan that keeps + credentials out of shipped plugin source and the graph. +- `plugin.ts`/`schema.ts`, the generic sandbox mapper and platform schema + from the retired runtime (below); `issue-tracker/` still imports + `schema.ts`. + +Current provider integrations are drive apps; see +[`../README.md`](../README.md#building-a-localthought-reflectorsyncablesdevonian-connector) +and [`../READINESS.md`](../READINESS.md). + +## The mock proxy + +It speaks the protocol of `integration-proxy` 0.2 (ontola/atomic-plugins#54, +[`../../integration-proxy/`](../../integration-proxy/)) on every route a +client uses, and checks every signature the way the real proxy does, so a +host that signs wrongly fails the e2e: + +| Route | What the mock does | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GET /connect?platform&redirect_uri&code_challenge&code_challenge_method=S256` | Consent page. No login and no `user_id`; the retired `user_id`/`credentials` parameters are refused. `redirect_uri` must be the lane's own `/app/integrations` (stricter than the real proxy). An API-key platform (a catalog document with an `apiKey` security scheme: `clockify`) shows an "API key" field and "Connect Clockify"; others show "Use LocalThought to sync {title} with this destination", as `integration-proxy/src/templates.rs` does. | +| `POST /connect/authorize` | The consent form. Stands in for the provider's OAuth and returns `redirect_uri?connection_code=` (single use, 5 min), or `?error=access_denied` on Cancel. | +| `POST /connect/redeem` | Signed (v2). `{code, code_verifier}`; the signer becomes the owner. Answers `{connection_id, platform, owner}`. | +| `GET /connections`, `DELETE /connections/{id}`, `POST /connections/{id}/agents`, `DELETE /connections/{id}/agents/{agent}`, `POST /runtimes`, `DELETE /runtimes/{agent}` | Signed (v2) management, owner only, with the real proxy's response shapes. | +| `ANY /proxy/{connection_id}/{platform}/{path}` | A frame's `Authorization: Capability .` plus a v2 signature by the capability's `cnf` key; or a request signed by the owner, a delegated app, or a registered runtime of a delegated app. Then the platform's fixture answers. | +| `GET /catalog`, `/catalog/.yaml`, `.selection.json` | The fixtures' catalog documents. | + +Checks, in the real proxy's order and with its `{error, message}` codes +(`integration-proxy/src/api_error.rs`): v2 request signatures (headers +`x-atomic-agent`, `x-atomic-public-key`, `x-atomic-timestamp`, +`x-atomic-signature`, `x-atomic-signature-version: 2`; message +`atomic-request-v2\nMETHOD\nURL\ntimestamp\nsha256(body)`; ±5 min; each +signed request accepted once), agent ids (`atomic:agent:` or +`did:ad:agent:`, either base64 alphabet; stored as +`atomic:agent:`), and capabilities (owner signature over +`integration-proxy-capability-v2\n` + the JSON claims, exact claim set, +`aud` = the mock's origin, `exp` at most 900 s ahead, connection and +platform against the route, the `app`'s delegation, then the request +signature by `cnf`). + +**The signed URL.** Signatures cover the full URL, so every client must +use exactly the mock's origin, `MOCK_PROXY_BASE_URL` (the real proxy's +`BASE_URL`). `serve.mjs` sets it, `INTEGRATION_PROXY_URL` (the browser's +proxy setting) and `ATOMIC_INTEGRATION_PROXY_URL` (the server's) to the +same `http://127.0.0.1:`. A request signed for `localhost` instead +fails with `bad_signature`. + +**What it does not have:** Postgres (state is in memory, per process), +real OAuth, sealed credentials (it holds none; a pasted API key is checked +for being non-empty and dropped), the 90-day idle sweep, the refresh lease, +and the SaaS access policy (every agent is admitted). + +**Shared vectors.** `mock-proxy.test.mjs` verifies the golden v2 request +vectors (`integration-proxy/tests/fixtures/atomic-request-v2-vectors.json`, +a copy of atomic-server's `lib/src/authentication_v2_vectors.json`) and +atomic-server's pinned capability vector against `mock-proxy-auth.mjs`, and +re-derives each vector's signature with the test signer. + +**Test-side routes** (no signature; the mock only listens locally): + +- `POST /__fixture/`: a fixture's `control(command)` (Clockify's + failure injection and data changes). +- `POST /fixture//`: one of the drivers a fixture lists + (`drivers`), with a JSON array of arguments. +- `GET /__mock/connections`: every connection with its owner, delegations + and `last_used_at`, and every runtime. No credential: the mock holds + none. +- `POST /__mock/revoke` `{connection_id, agent?}`: drops one delegation, or + the whole connection, as the owner would from another device. + +Fixtures live in their plugin folders; see +[`fixtures/index.mjs`](fixtures/index.mjs). They still see provider paths +under `/proxy//…`: the mock strips the connection id first. + +Run it alone, and its tests: ```sh MOCK_PROXY_PORT=19091 MOCK_FRONTEND_ORIGIN=http://localhost:6748 node integrations/localthought/mock-proxy.mjs -# Separate terminal, browser/data-browser: -VITE_INTEGRATION_PROXY_URL=http://127.0.0.1:19091 VITE_ATOMIC_SERVER_URL=http://127.0.0.1:19999 pnpm exec vite --host 127.0.0.1 --port 6748 -# Repository root: -node integrations/localthought/browser-smoke.mjs +node --test integrations/localthought/mock-proxy.test.mjs integrations/localthought/no-credentials-in-graph.test.mjs ``` -The mock is test-only. It uses a synthetic signed-in identity and data; never -deploy it. +## Deleted in #54 phase 2 + +`browser.ts` (`BrowserIntegrations`: catalog discovery, OAuth/PKCE and the +rotating-code proxy call), `settings.ts` (the proxy-origin setting and +per-origin connection keys), their tests and `browser-smoke.mjs`. They +spoke the proxy's retired connection codes (`Authorization: Bearer`, +`X-Connection-Code`), and nothing imported them: atomic-server's +`helpers/proxyConnections.ts` replaced them. The sections below describe +the runtime they belonged to, as history. ## Historical server-flow verification diff --git a/integrations/notion/README.md b/integrations/notion/README.md index 6805e1bac..991647a3b 100644 --- a/integrations/notion/README.md +++ b/integrations/notion/README.md @@ -77,8 +77,9 @@ What it does not do, and what is not verified: - The e2e shows the pinned host lets the app add Properties under its ontology and add them to its class's `recommends` (it checks the column datatypes). Only the fake store covers later edits to them. -- It depends on `store.proxy` (`request`, `connections`, `connect`), which - atomic-server gets from #52's relay (ontola/atomic-server#1657, pinned). +- It depends on `store.proxy` (`request`, `connections`, `connect`). Since + #54 phase 2 (ontola/atomic-server#1697, pinned) the host's frame client + calls the proxy itself with a capability and its own key. Without it, the app says so and fetches nothing. - The e2e runs against the mock proxy (see below). Nothing here has run against live Notion or a real proxy. @@ -94,8 +95,8 @@ host's consent bar and the mock proxy's consent page, then "Last synced" with 3 rows and their column types. It runs against the shared mock proxy's `notion` fixture (`fixtures/notion/`), so the lane has `platforms: ["notion"]` and `tiers: ["live", "e2e"]`. It needs an -`.atomic-server-ref` with the host relay (ontola/atomic-server#1657, merged -into `feat/plugin-debug`; the pin `bae5cdbe3` has it). The old +`.atomic-server-ref` with frame capabilities (ontola/atomic-server#1697; the +pin `11264e83e` has it). The old spec's two-way, PATCH and revoked-access checks have no read-only counterpart and were dropped (#68). diff --git a/integrations/pets/README.md b/integrations/pets/README.md index 39a3b4e16..3af539a0b 100644 --- a/integrations/pets/README.md +++ b/integrations/pets/README.md @@ -58,19 +58,25 @@ stylesheet. `package.json` and `pnpm-lock.yaml` and installed with `pnpm install --frozen-lockfile` in this folder; this repo's `syncables/src/` is not bundled. -- **Network.** Every request goes through the host's proxy relay, +- **Network.** Every request goes through `store.proxy.request({ platform, connectionId, path, method, body })` - (`app/transport.ts`). The top page holds the LocalThought connection (its - rotating code, in its own `localStorage`, bound to this app) and returns - only `{ status, headers, body }`. `transport.ts` refuses any URL outside + (`app/transport.ts`). The connection lives at the integration proxy, + owned by the signed-in user and delegated to this app; the host's frame + client calls the proxy with a short-lived capability from the page and a + key only it holds, and returns `{ status, headers, body }`. A refusal by + the proxy itself is thrown, not read as Pets' answer. `transport.ts` refuses any URL outside the document's `servers[0].url`, including provider-sent links. The bundle contains no `fetch`, storage or `Authorization` handling (`app/build.test.ts` checks this). - **Connecting.** "Connect Pets" calls `store.proxy.connect({ platform: 'pets' })`. The host, not the frame, draws a consent bar. Only a click there starts the PKCE handoff to the proxy. The proxy returns to - `/app/integrations`, the host redeems the code and navigates back to the - app, and the app finds its connection with `store.proxy.connections(...)`. + `/app/integrations`, the host redeems the code (signed with the user's + key), delegates the connection to the app and navigates back, and the app + finds its connection with `store.proxy.connections(...)`. If the person + already has a Pets connection, the bar offers "Use existing connection": + that only delegates it, and `connect` resolves `connected` without a + reload. There is no Pets-specific setup code in atomic-server. - **Writing.** `app/sync.ts` writes only inside the app's own subtree. It adds one Property per API field under the app's ontology, typed from the @@ -79,12 +85,12 @@ stylesheet. upserts one row per pet under the app's table, matched by `id`. A re-sync with no remote change writes nothing. -**Host requirement.** This needs the relay ops `proxy`, `proxyConnections` -and `proxyConnect` in atomic-server (atomic-server#1657, for #1624, merged -into `feat/plugin-debug` and in the pin). On a host without them the app says -so and stops. The -relay is the interim shape. #1624's scoped capability (#40, #54) is meant to -replace the rotating code without changing this app. +**Host requirement.** This needs `store.proxy` with frame capabilities +(atomic-server#1697, #54 phase 2, in the pin; its view ops are +`proxyCapability`, `proxyConnections` and `proxyConnect`). On a host without +`store.proxy` the app says so and stops. An older host with the #1657 relay +still has `store.proxy`, but its rotating connection codes are refused by +the 0.2 proxy. **Install.** The `pets` catalog entry is a drive app entry (#94): `app-module` is diff --git a/integrations/timesheets/README.md b/integrations/timesheets/README.md index 99650f369..ee382ef96 100644 --- a/integrations/timesheets/README.md +++ b/integrations/timesheets/README.md @@ -54,15 +54,18 @@ source and runs it in a null-origin, `allow-scripts`-only iframe - **Connecting.** "Connect Clockify" calls `store.proxy.connect({ platform: 'clockify' })`. The host, not the frame, draws a consent bar; only a click there starts the PKCE handoff to the - integration proxy, where the person enters their Clockify API key. The - host redeems the handoff, keeps the rotating connection code in its own - `localStorage`, bound to this app, and navigates back. The app finds the - connection with `store.proxy.connections({ platform: 'clockify' })`. The - frame and the drive never hold a code, token or connection id (#21). - Connections live in one browser: another browser shows "Not connected" - until the person connects there too. + integration proxy, where the person enters their Clockify API key; the + proxy keeps it, sealed. The host redeems the handoff (signed with the + user's key, so the user owns the connection), delegates it to this app + and navigates back. The app finds the connection with + `store.proxy.connections({ platform: 'clockify' })`. The app's code and + the drive never hold a key, token or capability (#21); the frame's + requests are signed by the host's frame client. + Connections live at the proxy under the user's agent, so another browser + signed in as the same user finds the same connection (not tried in the + e2e, which uses one browser). - **Setup.** Once connected, the frame reads the account (`/api/v1/user`) - and its workspaces (`/api/v1/workspaces`) through the relay and asks for + and its workspaces (`/api/v1/workspaces`) through the proxy and asks for a workspace and a 7- or 30-day look-back. It stores only the workspace id, the account id and the look-back on the App resource, as three Properties (`clockify-workspace`, `clockify-account`, `clockify-lookback-days`). @@ -161,8 +164,9 @@ node integrations/timesheets/app/build.mjs # -> app/dist/ui refolding, any permutation folds the same, snapshot + tail equals the full fold, two devices' diffs fold the same, fields equal the latest read. - **Host e2e** (`e2e/clockify.spec.ts`, the `timesheets` lane's `e2e` tier) - against the pinned atomic-server (`.atomic-server-ref`, which includes the - relay from atomic-server#1657) and the local mock proxy: connect through + against the pinned atomic-server (`.atomic-server-ref`, which includes + frame capabilities from atomic-server#1697) and the local mock proxy, + which checks the proxy's 0.2 signatures: connect through the consent bar, setup in the frame, Property and row writes through the real `/app-write`, 2 completed entries imported (running timer and break not), reopen with no duplicates, a changed entry updated in place, the From f9bc3f3617e53ac243faa64c07521af0ceaccb68 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 24 Sep 2026 17:26:33 +0200 Subject: [PATCH 8/8] timesheets: a proxy refusal never reads as a deleted entry (#54 phase 2 x #123 M1) After rebasing onto M1's observation log: relayTransport throws the integration proxy's own refusals (e.g. 404 unknown_connection) as a plain Error before requestJson wraps a response in ProxyError, so clockifyObserve's saysDeleted() cannot mistake a lost connection for a confirmed deletion. Pinned with a test. Two comments M1 carried over still said "relay". Co-Authored-By: Claude Opus 5.5 --- integrations/timesheets/app/fixtureProxy.ts | 4 ++-- integrations/timesheets/app/sync.test.ts | 4 ++++ integrations/timesheets/app/sync.ts | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/integrations/timesheets/app/fixtureProxy.ts b/integrations/timesheets/app/fixtureProxy.ts index f3e759d58..26ea44337 100644 --- a/integrations/timesheets/app/fixtureProxy.ts +++ b/integrations/timesheets/app/fixtureProxy.ts @@ -1,7 +1,7 @@ // @wc-ignore-file /** - * The shared mock proxy's Clockify fixture, reached the way the host relay - * reaches the real proxy: `{ platform, connectionId, path, query }` in, + * The shared mock proxy's Clockify fixture, reached the way the host's frame + * client reaches the real proxy: `{ platform, connectionId, path, query }` in, * `{ status, body }` out. Test-only; not bundled. */ import { diff --git a/integrations/timesheets/app/sync.test.ts b/integrations/timesheets/app/sync.test.ts index 2855932f9..90642d4bd 100644 --- a/integrations/timesheets/app/sync.test.ts +++ b/integrations/timesheets/app/sync.test.ts @@ -14,6 +14,7 @@ import { import { atomic, NAME } from './ontology.js'; import { ensureSchema, findSchema } from './schema.js'; import { GENERATED_TABLE_NOTE, syncClockify } from './sync.js'; +import { saysDeleted } from './clockifyObserve.js'; import { relayTransport, type ProxyTransport } from './transport.js'; const NOW = Date.parse('2026-09-23T12:00:00Z'); @@ -298,5 +299,8 @@ describe('relayTransport and the integration proxy', () => { await expect(transport.request('/v1/user')).rejects.toThrow( 'The integration proxy refused this connection (unknown_connection: no such connection). Connect again.', ); + // The proxy's own 404 must never read as "this entry was deleted". + const refused = await transport.request('/v1/user').catch(e => e); + expect(saysDeleted(refused)).toBe(false); }); }); diff --git a/integrations/timesheets/app/sync.ts b/integrations/timesheets/app/sync.ts index 5a02935c9..b3c51b9a6 100644 --- a/integrations/timesheets/app/sync.ts +++ b/integrations/timesheets/app/sync.ts @@ -112,7 +112,7 @@ export function rowValues( * * Row identity is a stored `clockify-entry-id` found with `store.query()`, * restricted to children of the app's table (`query` is drive-scoped). - * Requests are sequential; each is one relay round trip. + * Requests are sequential; each is one `store.proxy.request` round trip. */ export async function syncClockify( store: PluginStore,