feat: TangleAppsClient — self-service brokered hub-exec client (#73)

Adds the self-service external-apps client to the integrations/hub SDK, next to
TangleIntegrationsClient: register an app (registerApp), mint short-lived
sk-tan-broker- tokens unattended against a durable consented grant
(mintBrokerToken), exchange the one-time consent code (exchangeAuthCode),
list/revoke. The operator-allowlist-free (no TRUSTED_APPS) path any external
developer uses to integrate the hub.

Mirrors TangleIntegrationsClient (endpoint + fetchImpl seam, createTangle*Client
factory, IntegrationRuntimeError surface; BROKER_DISABLED → passthrough_disabled;
flat OAuth token endpoint handled). 5 tests; typecheck + build clean.

This is the canonical home — supersedes the draft in agent-runtime (PR closed).

Co-authored-by: drewstone <hello@webb.tools>

Author: drewstone

src/apps.ts

@@ -0,0 +1,211 @@
+import { IntegrationRuntimeError, normalizeIntegrationError } from './errors.js'
+
+/**
+ * Self-service external-apps client — the brokered hub-exec path.
+ *
+ * The operator-allowlist-free way to integrate the Tangle hub (no `TRUSTED_APPS`
+ * entry): a product registers itself ONCE (`registerApp` → client_id/secret),
+ * the end user consents ONCE per connection from their Tangle session (a browser
+ * step — not done here), and the product then mints short-lived
+ * `sk-tan-broker-…` tokens unattended (`mintBrokerToken`) for each
+ * `/v1/hub/exec` call. The durable grant means only the first consent needs a
+ * user; everything after is app-credential-only.
+ *
+ * Sits alongside {@link TangleIntegrationsClient} in the integrations/hub SDK —
+ * same `endpoint` + `fetchImpl` shape and the same `IntegrationRuntimeError`
+ * surface. Endpoints (platform API, e.g. https://id.tangle.tools):
+ *   POST /v1/apps                                      register (owner bearer)
+ *   GET  /v1/apps                                      list (owner bearer)
+ *   POST /v1/apps/:appId/revoke                        revoke (owner bearer)
+ *   POST /v1/apps/grants/:grantId/mint-broker-token    durable re-mint (app creds)
+ *   POST /v1/apps/oauth/token                          authorization_code → token
+ */
+
+export interface TangleAppsClientOptions {
+  /** Platform base URL (e.g. https://id.tangle.tools). */
+  endpoint: string
+  /** Test seam. Defaults to global `fetch`. */
+  fetchImpl?: typeof fetch
+}
+
+export interface RegisterAppInput {
+  name: string
+  redirectUris: string[]
+  allowedScopes: string[]
+  homepageUrl?: string
+}
+
+export interface AppSummary {
+  id: string
+  clientId: string
+  name: string
+  redirectUris: string[]
+  allowedScopes: string[]
+  homepageUrl?: string
+  createdAt?: string
+}
+
+export interface RegisteredApp extends AppSummary {
+  /** Shown ONCE at registration — persist it as a secret immediately. */
+  clientSecret: string
+}
+
+export interface BrokerToken {
+  /** The `sk-tan-broker-…` bearer for a single `/v1/hub/exec` call. */
+  accessToken: string
+  expiresIn: number
+  scope: string
+  connectionId?: string
+}
+
+interface PlatformEnvelope<T> {
+  success?: boolean
+  data?: T
+  error?: { code?: string; message?: string } | string
+}
+
+interface TokenResponse {
+  access_token: string
+  expires_in: number
+  scope: string
+  connection_id?: string
+}
+
+export class TangleAppsClient {
+  private readonly endpoint: string
+  private readonly fetchImpl: typeof fetch
+
+  constructor(options: TangleAppsClientOptions) {
+    this.endpoint = options.endpoint.replace(/\/$/, '')
+    this.fetchImpl = options.fetchImpl ?? fetch
+  }
+
+  /**
+   * Register a product as an app (ONE-TIME, with the owner's bearer — a Tangle
+   * session or `sk-tan-*` key). Returns the client_id + the once-shown
+   * client_secret; persist the secret immediately (never retrievable again).
+   */
+  async registerApp(input: RegisterAppInput, ownerBearer: string): Promise<RegisteredApp> {
+    const data = await this.request<{ app: AppSummary; clientSecret: string }>(
+      'POST',
+      '/v1/apps',
+      input,
+      ownerBearer,
+    )
+    return { ...data.app, clientSecret: data.clientSecret }
+  }
+
+  /** List the caller's registered apps (no secrets). */
+  async listApps(ownerBearer: string): Promise<AppSummary[]> {
+    const data = await this.request<{ apps: AppSummary[] }>('GET', '/v1/apps', undefined, ownerBearer)
+    return data.apps ?? []
+  }
+
+  /** Revoke an app and cascade-kill its grants + tokens. */
+  revokeApp(appId: string, ownerBearer: string): Promise<{ revoked: boolean }> {
+    return this.request('POST', `/v1/apps/${encodeURIComponent(appId)}/revoke`, {}, ownerBearer)
+  }
+
+  /**
+   * Durable re-mint: mint a fresh single-use `sk-tan-broker-` token against an
+   * existing consented grant using ONLY the app credentials — no user session,
+   * no `agc_` code. The runtime path: one call per `/v1/hub/exec`.
+   */
+  async mintBrokerToken(input: {
+    clientId: string
+    clientSecret: string
+    grantId: string
+    ttlSeconds?: number
+  }): Promise<BrokerToken> {
+    const data = await this.request<TokenResponse>(
+      'POST',
+      `/v1/apps/grants/${encodeURIComponent(input.grantId)}/mint-broker-token`,
+      {
+        client_id: input.clientId,
+        client_secret: input.clientSecret,
+        grant_id: input.grantId,
+        ...(input.ttlSeconds ? { ttl_seconds: input.ttlSeconds } : {}),
+      },
+    )
+    return toBrokerToken(data)
+  }
+
+  /**
+   * Exchange an `agc_` authorization code (from the user's one-time consent)
+   * for the first broker token + the durable grant. Use on the consent
+   * callback; afterward `mintBrokerToken` is enough.
+   */
+  async exchangeAuthCode(input: {
+    clientId: string
+    clientSecret: string
+    code: string
+    redirectUri: string
+    connectionId?: string
+  }): Promise<BrokerToken> {
+    const data = await this.request<TokenResponse>('POST', '/v1/apps/oauth/token', {
+      grant_type: 'authorization_code',
+      client_id: input.clientId,
+      client_secret: input.clientSecret,
+      code: input.code,
+      redirect_uri: input.redirectUri,
+      ...(input.connectionId ? { connection_id: input.connectionId } : {}),
+    })
+    return toBrokerToken(data)
+  }
+
+  private async request<T>(
+    method: 'GET' | 'POST' | 'DELETE',
+    path: string,
+    body?: unknown,
+    bearer?: string,
+  ): Promise<T> {
+    try {
+      const headers: Record<string, string> = { accept: 'application/json' }
+      if (bearer) headers.authorization = `Bearer ${bearer}`
+      if (body !== undefined) headers['content-type'] = 'application/json'
+
+      const response = await this.fetchImpl(`${this.endpoint}${path}`, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      })
+      const json = (await response.json().catch(() => undefined)) as PlatformEnvelope<T> | undefined
+
+      if (!response.ok || (json && json.success === false)) {
+        const platformCode = json?.error && typeof json.error === 'object' ? json.error.code : undefined
+        const message =
+          (json?.error && typeof json.error === 'object' && json.error.message) ||
+          (typeof json?.error === 'string' ? json.error : `Tangle apps request failed (HTTP ${response.status})`)
+        throw new IntegrationRuntimeError({
+          code: platformCode === 'BROKER_DISABLED' ? 'passthrough_disabled' : 'unknown',
+          message,
+          status: response.status,
+          metadata: { platformCode, path },
+        })
+      }
+      // The /v1/apps surface wraps in { success, data }; /v1/apps/oauth/token is flat.
+      return ((json && 'data' in json ? json.data : json) ?? ({} as T)) as T
+    } catch (error) {
+      if (error instanceof IntegrationRuntimeError) throw error
+      const normalized = normalizeIntegrationError(error)
+      throw new IntegrationRuntimeError({
+        code: normalized.code,
+        message: normalized.message,
+        metadata: { path, userAction: normalized.userAction },
+      })
+    }
+  }
+}
+
+export function createTangleAppsClient(options: TangleAppsClientOptions): TangleAppsClient {
+  return new TangleAppsClient(options)
+}
+
+function toBrokerToken(data: TokenResponse): BrokerToken {
+  return {
+    accessToken: data.access_token,
+    expiresIn: data.expires_in,
+    scope: data.scope,
+    connectionId: data.connection_id,
+  }
+}

src/index.ts

@@ -39,6 +39,7 @@ export * from './audit.js'
 export * from './approval.js'
 export * from './actions.js'
 export * from './bridge.js'
+export * from './apps.js'
 export * from './client.js'
 export * from './consumer.js'
 export * from './consent.js'

tests/apps-client.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest'
+import { TangleAppsClient, createTangleAppsClient } from '../src/apps'
+import { IntegrationRuntimeError } from '../src/errors'
+
+const ENDPOINT = 'https://id.tangle.tools'
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } })
+}
+
+function mockFetch(handler: (url: string, init?: RequestInit) => Response | Promise<Response>) {
+  return vi.fn(async (input: RequestInfo | URL, init?: RequestInit) =>
+    handler(typeof input === 'string' ? input : input.toString(), init),
+  ) as unknown as typeof fetch
+}
+
+describe('TangleAppsClient', () => {
+  it('registerApp posts to /v1/apps with the owner bearer and returns the once-shown secret', async () => {
+    let captured: { url: string; init?: RequestInit } | undefined
+    const client = createTangleAppsClient({
+      endpoint: ENDPOINT,
+      fetchImpl: mockFetch((url, init) => {
+        captured = { url, init }
+        return jsonResponse({
+          success: true,
+          data: {
+            app: { id: 'app_1', clientId: 'appcid_x', name: 'insurance-agent', redirectUris: ['https://insurance.tangle.tools/cb'], allowedScopes: ['gmail.messages_read'] },
+            clientSecret: 'appcs_secret',
+          },
+        })
+      }),
+    })
+    const app = await client.registerApp(
+      { name: 'insurance-agent', redirectUris: ['https://insurance.tangle.tools/cb'], allowedScopes: ['gmail.messages_read'] },
+      'sk-tan-owner',
+    )
+    expect(captured?.url).toBe(`${ENDPOINT}/v1/apps`)
+    expect(new Headers(captured?.init?.headers).get('authorization')).toBe('Bearer sk-tan-owner')
+    expect(app.clientId).toBe('appcid_x')
+    expect(app.clientSecret).toBe('appcs_secret')
+  })
+
+  it('mintBrokerToken uses app credentials (no user bearer) and returns a sk-tan-broker- token', async () => {
+    let captured: { url: string; init?: RequestInit } | undefined
+    const client = new TangleAppsClient({
+      endpoint: ENDPOINT,
+      fetchImpl: mockFetch((url, init) => {
+        captured = { url, init }
+        return jsonResponse({ success: true, data: { access_token: 'sk-tan-broker-abc', expires_in: 900, scope: 'gmail.messages_read', connection_id: 'conn_1' } })
+      }),
+    })
+    const tok = await client.mintBrokerToken({ clientId: 'appcid_x', clientSecret: 'appcs_secret', grantId: 'grant_42', ttlSeconds: 300 })
+    expect(captured?.url).toBe(`${ENDPOINT}/v1/apps/grants/grant_42/mint-broker-token`)
+    expect(new Headers(captured?.init?.headers).get('authorization')).toBeNull()
+    expect(JSON.parse(String(captured?.init?.body))).toMatchObject({ client_id: 'appcid_x', client_secret: 'appcs_secret', grant_id: 'grant_42', ttl_seconds: 300 })
+    expect(tok.accessToken).toBe('sk-tan-broker-abc')
+    expect(tok.accessToken.startsWith('sk-tan-broker-')).toBe(true)
+    expect(tok.expiresIn).toBe(900)
+    expect(tok.connectionId).toBe('conn_1')
+  })
+
+  it('exchangeAuthCode posts the agc_ code on the flat OAuth token endpoint', async () => {
+    let body: Record<string, unknown> | undefined
+    const client = new TangleAppsClient({
+      endpoint: ENDPOINT,
+      fetchImpl: mockFetch((_url, init) => {
+        body = JSON.parse(String(init?.body))
+        return jsonResponse({ access_token: 'sk-tan-broker-first', token_type: 'Bearer', expires_in: 3600, scope: 'gmail.messages_read' })
+      }),
+    })
+    const tok = await client.exchangeAuthCode({ clientId: 'appcid_x', clientSecret: 'appcs_secret', code: 'agc_code', redirectUri: 'https://insurance.tangle.tools/cb' })
+    expect(body).toMatchObject({ grant_type: 'authorization_code', code: 'agc_code', client_id: 'appcid_x' })
+    expect(tok.accessToken).toBe('sk-tan-broker-first')
+    expect(tok.expiresIn).toBe(3600)
+  })
+
+  it('maps the BROKER_DISABLED platform error to an IntegrationRuntimeError', async () => {
+    const client = new TangleAppsClient({
+      endpoint: ENDPOINT,
+      fetchImpl: mockFetch(() => jsonResponse({ success: false, error: { message: 'broker disabled', code: 'BROKER_DISABLED' } }, 503)),
+    })
+    const err = await client.mintBrokerToken({ clientId: 'a', clientSecret: 'b', grantId: 'g' }).catch((e: unknown) => e)
+    expect(err).toBeInstanceOf(IntegrationRuntimeError)
+    expect((err as IntegrationRuntimeError).code).toBe('passthrough_disabled')
+    expect((err as IntegrationRuntimeError).status).toBe(503)
+    expect((err as IntegrationRuntimeError).metadata).toMatchObject({ platformCode: 'BROKER_DISABLED' })
+  })
+
+  it('normalizes a trailing slash in endpoint', async () => {
+    let url = ''
+    const client = new TangleAppsClient({
+      endpoint: `${ENDPOINT}/`,
+      fetchImpl: mockFetch((u) => {
+        url = u
+        return jsonResponse({ data: { access_token: 'sk-tan-broker-z', expires_in: 60, scope: 's' } })
+      }),
+    })
+    await client.mintBrokerToken({ clientId: 'a', clientSecret: 'b', grantId: 'g' })
+    expect(url).toBe(`${ENDPOINT}/v1/apps/grants/g/mint-broker-token`)
+  })
+})