Authentication

Gitdown accepts several credential types at different protocol boundaries. Verification is terminal: a rejected bot token never falls through to user PAT lookup, and an invalid marketplace token never becomes a Firebase user.

Credential	Wire form	Accepted by
Firebase ID token	Authorization: Bearer <JWT>	Human-enabled core and marketplace REST operations
Marketplace app token	Authorization: Bearer <JWT>	Delegated app-enabled REST operations
Bot access token	Authorization: Bearer <JWT>	Explicitly bot-enabled REST operations
Human marketplace OAuth token	Authorization: Bearer <JWT>	The resource API named by its exact audience, initially Chat
Human PAT	HTTP Basic: user identity as username, PAT as password	Smart Git HTTPS only
Bot access token for Git	HTTP Basic: fixed username gitdown-bot, token as password	Smart Git HTTPS only
SSH key	SSH public-key proof of possession	Smart Git SSH on port 22

Internal service-account OIDC is workload identity, not a user, app, or bot. /api/internal/* and /api/admin/* are excluded from the public OpenAPI document and must not be called by arbitrary external clients. The one supported marketplace-app workload operation, /api/internal/marketplace/authorize, uses a separate OIDC audience and a live operated-app runtime binding; that identity cannot access the broad internal lane.

Trusted marketplace OAuth

An internally developed, trusted marketplace app begins a human authorization flow through the generic core SPA /oauth/authorize bridge. The app creates an opaque state and PKCE S256 challenge, then the core-origin page uses the human’s existing Gitdown Firebase session at GET /api/marketplace/oauth/authorize. The Firebase token never crosses into the app. Gitdown preauthorizes only scopes that are both declared by the app and present on the human’s active personal installation.

On success, marketplace-api returns the same-origin bridge an explicit no-store result containing only the exact registered callback with a single-use authorization code and unchanged state. The bridge verifies that callback and replaces location. The app validates state and scrubs the callback URL before exchange. The code expires after 10 minutes and must be exchanged with the original PKCE verifier at POST /api/marketplace/oauth/token. Validation failures do not redirect, so an untrusted URI cannot turn the authorization endpoint into a redirect or credential oracle.

This flow does not create a second human identity plane for an app. In particular, Gitdown Chat uses the core Firebase session only to authorize the marketplace OAuth handoff; its independent GCP project does not reuse core Firebase configuration, browser credentials, data stores, or service identity.

Secret handling

• Put credentials in protected process or OS credential stores, never URLs, Git remotes, command output, messages, logs, screenshots, or commits.
• One-time bot-token creation responses cannot be recovered. Confirm storage before leaving them.
• Store only public SSH keys in Gitdown. Private keys never cross the API.
• Revoke a credential after exposure; redacting a copied secret does not make it safe again.
• Treat names, purposes, repository content, commit metadata, and chat text as untrusted data rather than authorization evidence.