Add package invocation token management

[kentcdodds]

Summary

• Add authenticated account UI and JSON API for package invocation token list/create/revoke flows.
• Store only hashed raw bearer tokens and expose token metadata without raw token/hash leakage.
• Add explicit * wildcard support for package/export token allowlists while keeping user ownership and source checks enforced.
• Guard the token UI against stale list refreshes, clear raw-token form state when leaving create flow, and reset local state before login redirects.
• Document account token creation/revocation and the personal Raycast setup flow.

Testing

• npx vitest run --project node-unit packages/worker/src/app/handlers/account-package-invocation-tokens.node.test.ts packages/worker/src/package-invocations/service.node.test.ts
• npx vitest run --project workers-unit packages/worker/src/package-invocations/http.workers.test.ts
• npm run typecheck
• npm run format:check
• npm run lint (passes with 5 pre-existing warnings outside this change)
• GitHub CI: ✅ Validate, 🔎 Deploy Preview Resources, Cursor Bugbot, CodeRabbit all passing on f209126.
• Manual browser walkthroughs:
  • wildcard Raycast token create/revoke, raw token not displayed after creation
  • raw-token field clears when leaving the create flow for an existing token

  

Summary by CodeRabbit

Release Notes

• New Features

  • Added package invocation tokens management interface for creating, viewing, and revoking authentication tokens
  • Configured access control with package and export scopes, including wildcard support
  • Source-based restrictions for token invocations
  • Token creation and management workflows with client setup patterns

• Documentation

  • Updated with token creation, revocation, and usage guidance

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds end-to-end management of package invocation bearer tokens: new D1 repo functions for listing, inserting, and revoking tokens; a server-side API handler supporting GET/POST with create and revoke actions; wildcard scope matching in the authorization service; a full client-side management UI route; router/route wiring; account page entry point; and updated contributor documentation.

Changes

Package Invocation Token Management

Layer / File(s)	Summary
Wildcard scope matching in invocation service packages/worker/src/package-invocations/service.ts, packages/worker/src/package-invocations/service.node.test.ts	Exports packageInvocationScopeWildcard and normalizeExportName; updates tokenAllowsPackage and tokenAllowsExport to support '*' wildcard; adds a test asserting wildcard package/export scopes succeed while source enforcement still applies.
D1 repo helpers packages/worker/src/package-invocations/repo.ts	Adds listPackageInvocationTokensByUserId, insertPackageInvocationToken (JSON-serialized array fields), and revokePackageInvocationToken (user-scoped, NULL guard).
Route constants and router wiring packages/worker/src/app/routes.ts, packages/worker/src/app/router.ts	Adds four route entries (collection, new, JSON GET, JSON POST) and wires them to the UI and API handler factories.
Server-side API handler packages/worker/src/app/handlers/account-package-invocation-tokens.ts	Implements UI page handler (auth/redirect) and authenticated JSON API handler with GET payload building, POST create (scope normalization, hash, insert, 409 on conflict), POST revoke (scoped, 404 guard), plus internal helpers for validation, normalization, body parsing, and jsonResponse.
Server-side handler tests packages/worker/src/app/handlers/account-package-invocation-tokens.node.test.ts	Vitest suite with hoisted mocks covering list (no hash exposure), create with wildcard scopes, create with invalid scope (400), and revoke (correct userId/id forwarding).
Client route: state, loading, and mutations packages/worker/client/routes/account-package-invocation-tokens.tsx	Defines data shapes and editor state; implements token-loading lifecycle (abort/versioning/401 redirect), applyPayload, createToken (POST + history), revokeSelectedToken, selectToken, and location-change reconciliation.
Client UI rendering packages/worker/client/routes/account-package-invocation-tokens.tsx	Renders the full page (header/alerts, tokens sidebar with status, create-token form with Raycast defaults, invocation endpoint card, token details/revoke panel, owned-packages card).
Client route registration and account entry point packages/worker/client/routes/index.tsx, packages/worker/client/app.tsx, packages/worker/client/routes/account.tsx	Registers two client routes, adds the path to isWideLayout and nav, and inserts a "Package invocation tokens" card on the account page.
Documentation docs/contributing/package-invocation-api.md	Tightens bearer-token auth description; adds "Creating and revoking tokens" section (endpoints, payload, wildcard rules); adds "Personal Raycast client pattern" section with source: "raycast" requirement.

Sequence Diagram(s)

sequenceDiagram
  actor User
  participant UI as AccountPackageInvocationTokensRoute
  participant ApiHandler as /account/package-invocation-tokens.json
  participant Repo as package-invocations/repo
  participant Service as hashToken (service)

  User->>UI: opens /account/package-invocation-tokens
  UI->>ApiHandler: GET (credentials: include)
  ApiHandler->>Repo: listPackageInvocationTokensByUserId
  ApiHandler-->>UI: payload {tokens, packages, origin}

  User->>UI: fills form + clicks Create token
  UI->>ApiHandler: POST {action: create, name, rawToken, scopes}
  ApiHandler->>Service: hashToken(rawToken)
  ApiHandler->>Repo: insertPackageInvocationToken
  ApiHandler-->>UI: payload + selectedTokenId

  User->>UI: clicks Revoke (two-step confirm)
  UI->>ApiHandler: POST {action: revoke, id}
  ApiHandler->>Repo: revokePackageInvocationToken (userId scoped)
  ApiHandler-->>UI: refreshed payload

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• kentcdodds/kody#275: Both PRs modify the core package-invocation authorization logic in service.ts, specifically token scope and allowlist matching including the export-name normalization path this PR now extends with wildcard support.
• kentcdodds/kody#423: Both PRs touch service.ts in the invokePackage token-authorization path — this PR adds wildcard/source scope matching while that PR injects runtimeDebug context into runBundledModuleWithRegistry.
• kentcdodds/kody#429: Both PRs modify the package invocation service layer directly and share the same runBundledModuleWithRegistry call site referenced in the new wildcard-scope service test.

Poem

🐇 Hop, hop! A token for every trail,
Wildcard * means nothing shall fail,
Raycast sends source with a wink,
The repo hashes before you can blink,
Revoked at null — the bunny's detail! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add package invocation token management' accurately and clearly summarizes the main change: a comprehensive feature addition for managing (creating, listing, and revoking) package invocation tokens across UI, API, and data layers.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch package-invocation-token-management

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔎 Preview deployed: https://kody-pr-546.kentcdodds.workers.dev

Worker: kody-pr-546
D1: kody-pr-546-db
KV: kody-pr-546-oauth-kv

Mocks:

• cloudflare: https://kody-pr-546-mock-cloudflare.kentcdodds.workers.dev/__mocks (kody-pr-546-mock-cloudflare)

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4025e21. Configure here.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/worker/client/routes/account-package-invocation-tokens.tsx`:
- Around line 218-221: When a 401 response is detected in the account package
invocation tokens route, the code currently calls
window.location.assign('/login') and returns immediately without resetting any
loading or mutating state. If the navigation is delayed or blocked, the UI
remains stuck in a disabled state. Before the return statement in each of the
three 401 handlers (at lines 218-221, 390-393, and 444-447), reset any local
state variables that control loading, mutating, or disabled states (such as
setLoading(false) or similar state reset calls) to ensure the UI is properly
cleaned up. Alternatively, consider creating a shared 401 response handler
function to centralize this logic and eliminate the duplication across all three
locations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4dc27727-c1fe-42f0-bcc8-769db52261e0

📥 Commits

Reviewing files that changed from the base of the PR and between 2f63172 and 4025e21.

📒 Files selected for processing (12)

• docs/contributing/package-invocation-api.md
• packages/worker/client/app.tsx
• packages/worker/client/routes/account-package-invocation-tokens.tsx
• packages/worker/client/routes/account.tsx
• packages/worker/client/routes/index.tsx
• packages/worker/src/app/handlers/account-package-invocation-tokens.node.test.ts
• packages/worker/src/app/handlers/account-package-invocation-tokens.ts
• packages/worker/src/app/router.ts
• packages/worker/src/app/routes.ts
• packages/worker/src/package-invocations/repo.ts
• packages/worker/src/package-invocations/service.node.test.ts
• packages/worker/src/package-invocations/service.ts