@cat-factory/app 0.317.2 → 0.318.0

package/app/components/settings/ApiTokensPanel.vue

@@ -172,6 +172,7 @@ watch(
       newSecret.value = null
       return
     }
+    applyPrefill()
     try {
       await store.ensureLoaded()
     } catch (e) {
@@ -181,6 +182,16 @@ watch(
   { immediate: true },
 )
 
+/** Fill the create form from a new-API-key deep link (`useNewApiKeyDeepLink`), once. */
+function applyPrefill() {
+  const prefill = ui.apiTokensPrefill
+  if (!prefill) return
+  if (prefill.label) label.value = prefill.label
+  if (prefill.scope) scope.value = prefill.scope
+  if (prefill.runsAsSelf && canBindSelf.value) identity.value = 'self'
+  ui.apiTokensPrefill = null
+}
+
 async function createToken() {
   const trimmed = label.value.trim()
   if (!trimmed) return

package/app/composables/useNewApiKeyDeepLink.spec.ts

@@ -0,0 +1,53 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { captureNewApiKeyDeepLink } from './useNewApiKeyDeepLink'
+
+function setUrl(search: string): void {
+  history.replaceState(null, '', `/${search}`)
+}
+
+describe('captureNewApiKeyDeepLink', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    setUrl('')
+  })
+
+  it('parses the link an integration builds, and strips only its own params', () => {
+    setUrl('?newApiKey=1&label=sainte-beuve&scope=decide&runsAsSelf=1&ws=ws_1&keep=yes')
+    expect(captureNewApiKeyDeepLink()).toEqual({
+      label: 'sainte-beuve',
+      scope: 'decide',
+      runsAsSelf: true,
+      workspaceId: 'ws_1',
+    })
+    expect(window.location.search).toBe('?keep=yes')
+    expect(captureNewApiKeyDeepLink()).toBeNull()
+  })
+
+  it('opens the form at its defaults when the link names nothing else', () => {
+    setUrl('?newApiKey=1')
+    expect(captureNewApiKeyDeepLink()).toEqual({
+      label: null,
+      scope: null,
+      runsAsSelf: false,
+      workspaceId: null,
+    })
+    expect(window.location.search).toBe('')
+  })
+
+  it('drops a scope this build does not know rather than guessing one', () => {
+    setUrl('?newApiKey=1&scope=superuser')
+    expect(captureNewApiKeyDeepLink()).toMatchObject({ scope: null })
+  })
+
+  it('cuts a label to what the form accepts', () => {
+    setUrl(`?newApiKey=1&label=${'x'.repeat(200)}`)
+    expect(captureNewApiKeyDeepLink()?.label).toHaveLength(120)
+  })
+
+  it('ignores a URL without the link, and leaves its query alone', () => {
+    setUrl('?label=other&scope=admin')
+    expect(captureNewApiKeyDeepLink()).toBeNull()
+    expect(window.location.search).toBe('?label=other&scope=admin')
+  })
+})

package/app/composables/useNewApiKeyDeepLink.ts

@@ -0,0 +1,87 @@
+/**
+ * Boot-time replay of a NEW API KEY deep link:
+ * `?newApiKey=1&label=<label>&scope=<scope>&runsAsSelf=1&ws=<id>`.
+ *
+ * An integration that needs a person's OWN key (one bound to them, which is what lets a run use
+ * their personal model subscription) cannot mint it for them: a bound key can only be minted by
+ * its owner, signed in. It sends the person here instead, and the API tokens window opens with the
+ * create form filled in. Nothing is minted until the person clicks create.
+ *
+ * Every parameter but `newApiKey` is optional. A scope this build does not know is dropped rather
+ * than guessed at, and `runsAsSelf` only takes effect where there is a signed-in person to bind
+ * (`ApiTokensPanel` withholds the choice otherwise). Signing in first keeps the query
+ * (`postSignInUrl`). The format is published next to `?addRepo=` in the public API docs.
+ */
+import { PUBLIC_API_SCOPES } from '@cat-factory/contracts'
+import { watch } from 'vue'
+import type { PublicApiScope } from '~/types/publicApiKeys'
+import { useUiStore } from '../stores/ui'
+import { useWorkspaceStore } from '../stores/workspace'
+
+/** What the API tokens window's create form is opened with. Absent fields keep their defaults. */
+export interface NewApiKeyPrefill {
+  label: string | null
+  scope: PublicApiScope | null
+  runsAsSelf: boolean
+}
+
+interface PendingNewApiKeyLink extends NewApiKeyPrefill {
+  workspaceId: string | null
+}
+
+const NEW_API_KEY_LINK_PARAMS = ['newApiKey', 'label', 'scope', 'runsAsSelf', 'ws'] as const
+
+/** The form's own label limit, so a prefill never starts out invalid. */
+const LABEL_MAX_LENGTH = 120
+
+function scopeOf(value: string | null): PublicApiScope | null {
+  return (PUBLIC_API_SCOPES as readonly string[]).includes(value ?? '')
+    ? (value as PublicApiScope)
+    : null
+}
+
+/**
+ * Read (and strip) a new-API-key link from the current URL, or null when there is none. Called
+ * before `workspace.init()` so `ws` can pin the board.
+ */
+export function captureNewApiKeyDeepLink(): PendingNewApiKeyLink | null {
+  if (typeof window === 'undefined') return null
+  const params = new URLSearchParams(window.location.search)
+  if (params.get('newApiKey') !== '1') return null
+  const label = params.get('label')?.trim().slice(0, LABEL_MAX_LENGTH) || null
+  const link: PendingNewApiKeyLink = {
+    label,
+    scope: scopeOf(params.get('scope')),
+    runsAsSelf: params.get('runsAsSelf') === '1',
+    workspaceId: params.get('ws'),
+  }
+  for (const key of NEW_API_KEY_LINK_PARAMS) params.delete(key)
+  const qs = params.toString()
+  history.replaceState(null, '', window.location.pathname + (qs ? `?${qs}` : ''))
+  return link
+}
+
+/** Capture a new-API-key link and, once the board has hydrated, open the window with it. */
+export function useNewApiKeyDeepLink(): void {
+  const link = captureNewApiKeyDeepLink()
+  if (!link) return
+
+  const workspace = useWorkspaceStore()
+  const ui = useUiStore()
+  if (link.workspaceId) workspace.workspaceId = link.workspaceId
+
+  // One-shot, as `useAddRepoDeepLink` is: a later refresh must not reopen a window the person
+  // closed, and `immediate` runs the callback before `stop` is bound.
+  let applied = false
+  let stop: (() => void) | undefined
+  stop = watch(
+    () => workspace.ready,
+    (ready) => {
+      if (!ready || applied) return
+      applied = true
+      ui.openApiTokens({ label: link.label, scope: link.scope, runsAsSelf: link.runsAsSelf })
+      stop?.()
+    },
+    { immediate: true },
+  )
+}

package/app/pages/index.vue

@@ -185,6 +185,8 @@ onMounted(() => {
   useRunDeepLink()
   // `?addRepo=<owner>/<name>`: an integration sending a person to add a service for a repository.
   useAddRepoDeepLink()
+  // `?newApiKey=1`: an integration sending a person to mint a key bound to them.
+  useNewApiKeyDeepLink()
   // `?view=queue` / `?view=board`: a link that opens one of the board's two views.
   views.consumeDeepLink()
   void workspace.init()

package/app/stores/ui/modals.ts

@@ -11,6 +11,7 @@ import type {
   ProviderConnectionKind,
 } from '~/types/providerConnections'
 import type { AddServicePrefill } from '~/composables/useAddRepoDeepLink'
+import type { NewApiKeyPrefill } from '~/composables/useNewApiKeyDeepLink'
 import type { PendingContext } from '~/composables/useContextLinking'
 import {
   infraSetupDismissalKey,
@@ -667,6 +668,8 @@ function createIntegrationPanelModals(resetHubReturn: ResetHubReturn) {
   // API access tokens: the workspace's inbound public-API keys external systems present to
   // the `/api/v1` surface. Opened from the Integrations hub.
   const apiTokensOpen = ref(false)
+  // The create form a new-API-key deep link opened the window with, consumed on open.
+  const apiTokensPrefill = ref<NewApiKeyPrefill | null>(null)
   // Opened and closed by `createBuilderModelConfigHandoff`, which hands the pipeline builder over.
   const modelConfigOpen = ref(false)
   // LLM-vendor subscription credentials (the token pool powering the Claude Code
@@ -722,12 +725,14 @@ function createIntegrationPanelModals(resetHubReturn: ResetHubReturn) {
   function closeReports() {
     reportsOpen.value = false
   }
-  function openApiTokens() {
+  function openApiTokens(prefill: NewApiKeyPrefill | null = null) {
     resetHubReturn()
+    apiTokensPrefill.value = prefill
     apiTokensOpen.value = true
   }
   function closeApiTokens() {
     apiTokensOpen.value = false
+    apiTokensPrefill.value = null
   }
   function openVendorCredentials(tab = 'pool') {
     resetHubReturn()
@@ -770,6 +775,7 @@ function createIntegrationPanelModals(resetHubReturn: ResetHubReturn) {
     operatorDashboardOpen,
     reportsOpen,
     apiTokensOpen,
+    apiTokensPrefill,
     modelConfigOpen,
     vendorCredentialsOpen,
     vendorCredentialsTab,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.317.2",
+  "version": "0.318.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",