RFC-0006: Extension Server Authentication

[github-actions[bot]]

📄 RFC Doc: 0006-extension-server-authentication.md

---

Extension Server Authentication

Authors: @LalitMaganti

Status: Adopted

Problem

RFC-0005 (Perfetto UI Server Extensions) defines a system where users can
configure HTTP(S) endpoints to serve Perfetto UI extensions (macros, SQL
modules, proto descriptors). These extension servers may require authentication
to access:

1. Private repositories: GitHub repos with restricted access
2. Corporate servers: Internal servers behind SSO
3. API-protected servers: Servers requiring API keys or tokens

The authentication system needs to:

• Work entirely client-side (Perfetto UI has no backend)
• Support multiple authentication mechanisms
• Store credentials alongside server configuration
• Support multiple servers with different credentials

Decision

Implement authentication as part of the server configuration itself, using
per-server-type discriminated unions for auth options. Credentials are stored
inline with the server settings in localStorage, with secret fields annotated
via Zod metadata so they can be stripped when sharing server configurations.

Design

Authentication Per Server Type

Authentication is configured when adding or editing a server in Settings. Each
server type (GitHub, HTTPS) has its own set of supported auth mechanisms,
modeled as discriminated unions.

GitHub servers:

Auth type	Description
none	Public repos (no auth required)
github_pat	Personal Access Token for private repos

HTTPS servers:

Auth type	Description
none	Public servers (no auth required)
https_basic	Username/password (Basic auth header)
https_apikey	API key via Bearer, X-API-Key, or custom header
https_sso	Cookie-based SSO with automatic iframe refresh

Storage

Credentials are stored inline with the server configuration in the Perfetto
settings system (localStorage). There is no separate credential store.

Secret fields (PAT, passwords, API keys) are annotated with
.meta({secret: true}) in the Zod schema. This metadata is used to strip
secrets when generating shareable server URLs.

// GitHub auth
const githubAuthSchema = z.discriminatedUnion('type', [
  z.object({type: z.literal('none')}),
  z.object({
    type: z.literal('github_pat'),
    pat: z.string().meta({secret: true}).default(''),
  }),
]);

// HTTPS auth
const httpsAuthSchema = z.discriminatedUnion('type', [
  z.object({type: z.literal('none')}),
  z.object({
    type: z.literal('https_basic'),
    username: z.string().meta({secret: true}).default(''),
    password: z.string().meta({secret: true}).default(''),
  }),
  z.object({
    type: z.literal('https_apikey'),
    keyType: z.enum(['bearer', 'x_api_key', 'custom']).default('bearer'),
    key: z.string().meta({secret: true}).default(''),
    customHeaderName: z.string().default(''),
  }),
  z.object({type: z.literal('https_sso')}),
]);

Request Construction

All URL construction and auth header injection happens in a single
buildFetchRequest() function that takes a server configuration and a resource
path, producing a URL and RequestInit:

GitHub PAT:

• Uses the GitHub API (api.github.com/repos/.../contents/...) instead of
  raw.githubusercontent.com
• Adds Authorization: token {pat} header
• Adds Accept: application/vnd.github.raw+json header

GitHub (no auth):

• Uses raw.githubusercontent.com directly (avoids GitHub API rate limits)

HTTPS Basic:

• Adds Authorization: Basic {base64(username:password)} header

HTTPS API Key:

• bearer → Authorization: Bearer {key}
• x_api_key → X-API-Key: {key}
• custom → {customHeaderName}: {key}

HTTPS SSO:

• Adds credentials: 'include' to the fetch request to send cookies

SSO Cookie Refresh

For SSO-authenticated servers, a 403 response may indicate an expired session
cookie. The UI handles this automatically:

1. On 403 from an SSO server, load the server's base URL in a hidden iframe
2. The iframe follows SSO redirects; on onload, the browser has fresh cookies
3. Retry the original request once with the refreshed cookies
4. If the retry also fails, report the error normally

The iframe has a 10-second timeout. This flow is transparent to the user.

Server Addition Flow

1. User clicks "Add Server" in Settings → Extension Servers
2. Modal appears with server type selection (GitHub or HTTPS)
3. User fills in connection details and selects auth type
4. UI fetches manifest to discover modules
5. User selects which modules to enable
6. Click "Save" to persist; page reload applies changes

Auth configuration happens upfront during server addition, not on-demand after
a 401/403. This is simpler and avoids the complexity of detecting auth
requirements at runtime.

Sharing Servers

Servers can be shared via URL (?addServer=<base64>). When generating the
share URL, the stripSecrets() function removes all fields annotated with
.meta({secret: true}), replacing the auth with {type: 'none'}. The
recipient must configure their own credentials after importing.

Locked (Embedder-Configured) Servers

Embedder-configured servers (e.g., Google's internal server auto-added for
Googlers) are marked as locked: true. Locked servers:

• Cannot be deleted or have their connection details edited
• Can still be enabled/disabled by the user
• Can have their module selection changed
• Auth type is set by the embedder (e.g., SSO for corporate servers)

Security Considerations

Credential Storage:

• Stored in localStorage in plaintext alongside server configuration
• Protected by browser same-origin policy
• Secret fields annotated with Zod metadata for stripping during export/share
• Rationale: Perfetto runs entirely in-browser without privileged services.
  Browser's same-origin protection is the security boundary. This follows
  industry practice (GitHub, VS Code, etc.).

User controls:

• View/edit/delete credentials via the server edit modal
• Credentials never sent to perfetto.dev servers
• Shared URLs have credentials automatically stripped

CORS requirements:

All HTTPS extension servers must set CORS headers:

Access-Control-Allow-Origin: https://ui.perfetto.dev
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Authorization, Content-Type, X-API-Key

SSO servers additionally need Access-Control-Allow-Credentials: true.

Future Work

• GitHub OAuth Device Flow: Could replace PAT with proper OAuth for better
  UX (no manual token creation). Requires registering a Perfetto GitHub App.
• GCS/S3 support: Cloud storage authentication for extension servers hosted
  on Google Cloud Storage or AWS S3.
• Credential reveal UI: Show masked credentials with click-to-reveal.
• Token refresh: Automatic refresh for OAuth-based tokens.

---

💬 Discussion Guidelines:

• This discussion is automatically synced with the RFC document
• Please provide constructive feedback and suggestions

[github-actions[bot]]

📝 RFC Document Updated

View changes: Commit History