:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(hog): parse flags, env vars and stored logins into branded types (#129794)
Rafael Audibertdceeb5c9e935
diff --git a/hog/AGENTS.md b/hog/AGENTS.mdindex 1a19000d632b..cecd8fc261dc 100644--- a/hog/AGENTS.md+++ b/hog/AGENTS.md@@ -58,6 +58,7 @@ export default defineCommand({- `exitCode` is for results that are not failures but that a script must branch on, like `hog query check` finding errors.- `--raw` is global: it prints the result of `run` as JSON and skips both views. Do not add per-command `--raw` or `--debug` flags; return enough data from `run` instead.- An argument with `stdin: true` reads stdin when the caller passes `-`, and fails when it is empty. `hog commands` tells agents which arguments accept it.+- Data that enters hog, such as flags, env vars, files, keychain items and answers from PostHog, is parsed into a typed value at the boundary with a zod schema. It is not checked and then passed on as a plain string. A branded value, such as a `Host`, a `ProjectId` or a token kind, comes only from its factory, such as `parseHost` or `parseProjectId`.- Commands reach the outside world only through `ctx` (`ctx.posthog()`, `ctx.runtime`), so tests can fake it. Do not read `process` or call `fetch` directly.- Import heavy dependencies inside `run` with `await import()`. Every command module loads on every call, so a top-level import of a large library slows down all commands.- Declare `scopes`. `hog commands` lists them for agents, and a 403 names them in its hint.diff --git a/hog/src/cli.ts b/hog/src/cli.tsindex 03ce4f196602..b1fdd9bb38d8 100644--- a/hog/src/cli.ts+++ b/hog/src/cli.ts@@ -5,7 +5,9 @@ import { COMMANDS } from '@/commands'import { resolveMode, type Mode, type OutputFormat } from '@/core/agent'import {argumentSyntax,+ longFlag,optionFlags,+ parseOption,type Command,type CommandTree,type Group,@@ -184,6 +186,11 @@ function createProgram(runtime: Runtime, mode: Mode, state: RunState, telemetry:resolveCredentials({ ...runtime, writeStderr: () => {} }, { ...globals, skipStore: true })const commandRuntime = networkRuntime(runtime, globals)const options = self.opts()+ // An empty value, often an unset shell variable, fails here instead of falling back to a+ // default, such as the login's project.+ for (const [name, spec] of Object.entries(node.options ?? {})) {+ options[name] = parseOption(spec, options[name], longFlag(name), 'invalid_input')+ }if (envFlag(runtime.env, DRY_RUN_ENV)) {if (Object.hasOwn(node.options ?? {}, 'dryRun')) {options.dryRun = truediff --git a/hog/src/commands/api/api.test.ts b/hog/src/commands/api/api.test.tsindex 56e71b6c3d0e..2a2fa1b9b1d1 100644--- a/hog/src/commands/api/api.test.ts+++ b/hog/src/commands/api/api.test.ts@@ -100,6 +100,12 @@ describe('hog api', () => {['input the schema rejects', ['api', 'call', 'flag-list', '{"limit":"x"}'], 'invalid_input', 2],['a destructive tool without --confirm', ['api', 'call', 'flag-delete', '{"id":1}'], 'needs_confirmation', 1],['an empty --project-id', ['api', 'call', 'flag-list', '{}', '--project-id', ''], 'invalid_input', 2],+ [+ 'a --project-id that is not a number',+ ['api', 'call', 'flag-list', '{}', '--project-id', 'abc'],+ 'invalid_input',+ 2,+ ],['an empty --organization-id',['api', 'call', 'flag-list', '{}', '--organization-id', ' '],@@ -123,7 +129,7 @@ describe('hog api', () => {],['an organization override drops the saved project',- ['--organization-id', 'org-b'],+ ['--organization-id', '0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b'],{ ok: 1 },[{@@ -132,7 +138,7 @@ describe('hog api', () => {connection: {apiKey: 'phx_test',host: 'https://ph.example.com',- organizationId: 'org-b',+ organizationId: '0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b',clientName: 'hog',clientVersion: expect.any(String),},@@ -194,7 +200,13 @@ describe('hog api', () => {test.each([['an unlimited key reaches the project', [], 200, undefined, true],["a key limited to the project's organization reaches it", ['org-a'], 200, 'org-a', true],- ['a key limited to another organization does not', ['org-b'], 200, 'org-a', false],+ [+ 'a key limited to another organization does not',+ ['0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b'],+ 200,+ 'org-a',+ false,+ ],["a key without project:read can't tell", ['org-a'], 403, undefined, null],])('access: %s', async (_name, scopedOrganizations, status, projectOrganization, projectAllowed) => {const result = await runHog(['api', 'access'], {diff --git a/hog/src/commands/api/call.ts b/hog/src/commands/api/call.tsindex 8a3c4bfdc83e..f3e73deef8da 100644--- a/hog/src/commands/api/call.ts+++ b/hog/src/commands/api/call.ts@@ -1,6 +1,7 @@import { defineCommand } from '@/core/command'import { EXIT_USAGE, HogError } from '@/core/errors'import { findTool, grantedScopes, missingScopesError, toHogError, withApiConnection } from '@/posthog/api-tools'+import { parseOrganizationId, parseProjectId } from '@/posthog/ids'function parseInput(text: string | undefined): Record<string, unknown> {if (text === undefined) {@@ -37,10 +38,16 @@ export default defineCommand({options: {dryRun: { type: 'boolean', description: 'Check the input against the schema without calling the tool' },confirm: { type: 'boolean', description: 'Allow a tool that changes or deletes data it cannot restore' },- projectId: { type: 'string', placeholder: 'id', description: 'Call the tool in this project instead' },+ projectId: {+ type: 'string',+ placeholder: 'id',+ parse: parseProjectId,+ description: 'Call the tool in this project instead',+ },organizationId: {type: 'string',placeholder: 'id',+ parse: parseOrganizationId,description: 'The organization for organization-level tools',},},diff --git a/hog/src/commands/auth/auth.test.ts b/hog/src/commands/auth/auth.test.tsindex 0860da8e37b7..874ca139c831 100644--- a/hog/src/commands/auth/auth.test.ts+++ b/hog/src/commands/auth/auth.test.ts@@ -555,6 +555,27 @@ describe('hog auth login', () => {})+ test.each([+ ['a personal API key without the phx_ prefix', KEYCHAIN_LOGIN.files, { apiKey: 'unprefixedkey123' }, null],+ [+ 'an OAuth login without token prefixes, which it says it could not revoke',+ OAUTH_LOGIN.files,+ { accessToken: 'legacyaccess', refreshToken: 'legacyrefresh' },+ false,+ ],+ ])('logout removes a stored key hog can no longer read: %s', async (_name, files, secret, revoked) => {+ const result = await runHog(['auth', 'logout'], {+ env: { CLAUDECODE: '1' },+ files,+ keychain: { [EU]: JSON.stringify(secret) },+ })++ expect(result.exitCode).toBe(0)+ expect(result.json()).toMatchObject({ status: 'logged_out', revoked })+ expect(result.requests).toEqual([])+ expect(result.keychain).toEqual({})+ })+test.each([['revokes an OAuth login in PostHog before it removes it', 200, true],['says when PostHog could not revoke the login, and still removes it', 503, false],@@ -647,6 +668,8 @@ describe('hog auth login', () => {[HOG_CREDENTIALS_FILE]: JSON.stringify({'https://us.posthog.com': { apiKey: 'phx_us' },'https://posthog.example.com': { apiKey: 'phx_orphan' },+ // An older hog keyed `localhost:8000` by its origin, which is "null".+ null: { apiKey: 'phx_unreadable' },}),[PENDING_FILE]: PENDING,},diff --git a/hog/src/commands/auth/login.ts b/hog/src/commands/auth/login.tsindex 044134f720e3..f90580298da3 100644--- a/hog/src/commands/auth/login.ts+++ b/hog/src/commands/auth/login.ts@@ -4,28 +4,21 @@ import type { Context } from '@/core/context'import { EXIT_USAGE, HogError } from '@/core/errors'import { escapeControls } from '@/core/output'import type { Prompts } from '@/core/prompts'+import { validationError } from '@/core/schema'import { PersonalAPIKey, type AccessKey } from '@/posthog/access-key'import type { StoreChoice } from '@/posthog/credential-store/types'-import { checkApiKey, checkHost, checkProjectId } from '@/posthog/credentials'import { LOGIN_SCOPES, READ_ONLY_LOGIN_SCOPES } from '@/posthog/device-auth'-import { trimHost } from '@/posthog/host'+import { hostKey, HostSchema, parseHost, type Host } from '@/posthog/host'+import { parseProjectId, ProjectIdSchema } from '@/posthog/ids'import { loginFlow, loginWait, saveLogin, type LoggedIn } from '@/posthog/login/flow'+import { parsePersonalApiKey, PersonalApiKeySchema } from '@/posthog/tokens'-const REGIONS = { us: 'https://us.posthog.com', eu: 'https://eu.posthog.com' } as const+const REGIONS = { us: parseHost('https://us.posthog.com'), eu: parseHost('https://eu.posthog.com') }// A posthog.json comes with the repository, so it only picks between the PostHog Cloud regions. A// login to any other host needs --host, so a repository can't send a person's login elsewhere.-function cloudRegion(host: string | undefined): string | undefined {- if (host === undefined) {- return undefined- }- let origin: string- try {- origin = new URL(host).origin- } catch {- return undefined- }- return Object.values(REGIONS).find((region) => region === origin)+function cloudRegion(host: Host | undefined): Host | undefined {+ return host && Object.values(REGIONS).find((region) => hostKey(region) === hostKey(host))}type LoginResult =@@ -70,10 +63,21 @@ async function finish(ctx: Context, key: AccessKey): Promise<LoginResult> {}async function keyLogin(ctx: Context, prompts: Prompts): Promise<LoginResult> {- const host = await prompts.text('PostHog host', { initialValue: REGIONS.us, validate: checkHost })- const projectId = await prompts.text('Project ID, the number in your project URL', { validate: checkProjectId })- const apiKey = await prompts.password('Personal API key', { validate: checkApiKey })- const key = new PersonalAPIKey({ host: trimHost(host), projectId, apiKey })+ const host = await prompts.text('PostHog host', {+ initialValue: REGIONS.us,+ validate: (value) => validationError(HostSchema, value),+ })+ const projectId = await prompts.text('Project ID, the number in your project URL', {+ validate: (value) => validationError(ProjectIdSchema, value),+ })+ const apiKey = await prompts.password('Personal API key', {+ validate: (value) => validationError(PersonalApiKeySchema, value),+ })+ const key = new PersonalAPIKey({+ host: parseHost(host),+ projectId: parseProjectId(projectId),+ apiKey: parsePersonalApiKey(apiKey),+ })return finish(ctx, key)}@@ -131,7 +135,7 @@ export default defineCommand({}let host =- ctx.globals.host?.replace(/\/+$/, '') ??+ ctx.globals.host ??(options.region ? REGIONS[options.region] : undefined) ??cloudRegion((await ctx.config())?.config.host)if (!host) {diff --git a/hog/src/commands/auth/migrate.ts b/hog/src/commands/auth/migrate.tsindex dc3187c6de25..e83ed8441981 100644--- a/hog/src/commands/auth/migrate.ts+++ b/hog/src/commands/auth/migrate.ts@@ -1,12 +1,13 @@import { defineCommand } from '@/core/command'-import { HogError } from '@/core/errors'import { escapeControls } from '@/core/output'import { PersonalAPIKey } from '@/posthog/access-key'import { parseJson } from '@/posthog/credential-store/helpers'import type { StoreChoice } from '@/posthog/credential-store/types'-import { checkApiKey, checkHost, checkProjectId, DEFAULT_HOST, posthogFile } from '@/posthog/credentials'-import { trimHost } from '@/posthog/host'+import { DEFAULT_HOST, posthogFile } from '@/posthog/credentials'+import { parseHost } from '@/posthog/host'+import { parseProjectId } from '@/posthog/ids'import { saveLogin } from '@/posthog/login/flow'+import { parsePersonalApiKey } from '@/posthog/tokens'type MigrateResult =| {@@ -45,17 +46,14 @@ export default defineCommand({throw error}const stored = parseJson(text) as { token?: unknown; env_id?: unknown; host?: unknown } | null | undefined- const apiKey = typeof stored?.token === 'string' ? stored.token : ''- const projectId = stored?.env_id === undefined ? '' : String(stored.env_id)- const host = trimHost(typeof stored?.host === 'string' ? stored.host : DEFAULT_HOST)- const problem = checkApiKey(apiKey) ?? checkProjectId(projectId) ?? checkHost(host)- if (problem) {- throw new HogError(- 'invalid_legacy_credentials',- `hog couldn't move the key in ${legacyFile}. ${problem}`,- 'Run `hog auth login` to log in instead.'- )+ const failure = {+ code: 'invalid_legacy_credentials',+ context: `hog couldn't move the key in ${legacyFile}.`,+ hint: 'Run `hog auth login` to log in instead.',}+ const apiKey = parsePersonalApiKey(stored?.token, failure)+ const projectId = parseProjectId(stored?.env_id, failure)+ const host = typeof stored?.host === 'string' ? parseHost(stored.host, failure) : DEFAULT_HOSTconst key = new PersonalAPIKey({ host, projectId, apiKey })const loggedIn = await saveLogin(runtime, key)const { store, credentialsPath, keychainError } = loggedIndiff --git a/hog/src/core/command.ts b/hog/src/core/command.tsindex 230a4adee4cc..12415cba35a7 100644--- a/hog/src/core/command.ts+++ b/hog/src/core/command.ts@@ -1,5 +1,7 @@import type { Context } from './context'+import { EXIT_USAGE } from './errors'import type { Output } from './output'+import type { ParseFailure } from './schema'import { kebabCase } from './text'export interface ArgumentSpec {@@ -32,6 +34,9 @@ export type OptionSpec =choices?: readonly string[]// The option can repeat, as in `--var a=1 --var b=2`, and its value is a list.multiple?: boolean+ // Turns the text into the value the command gets, such as a `Host`. It throws with `failure`+ // when the text is not valid, so a bad flag or env var fails before the command runs.+ parse?: (raw: string, failure: ParseFailure) => unknown} & OptionSource)type ArgumentValues<Args> = {@@ -47,7 +52,9 @@ export type OptionValues<Options> = {? boolean | undefined: Options[Name] extends { multiple: true }? string[] | undefined- : (Options[Name] extends { choices: readonly (infer Choice)[] } ? Choice : string) | undefined+ : Options[Name] extends { parse: (...args: never[]) => infer Parsed }+ ? Parsed | undefined+ : (Options[Name] extends { choices: readonly (infer Choice)[] } ? Choice : string) | undefined}interface CommandInput<Args, Options> {@@ -131,8 +138,20 @@ export function defineLegacy(definition: Omit<Legacy, 'kind'>): Legacy {return { kind: 'legacy', ...definition }}+// `source` names where the value came from, such as `--host` or `HOG_HOST`, so the error says what to fix.+export function parseOption(spec: OptionSpec, value: unknown, source: string, code: string): unknown {+ if (spec.type !== 'string' || !spec.parse || value === undefined) {+ return value+ }+ return spec.parse(String(value), { code, context: `${source} is not valid.`, exitCode: EXIT_USAGE })+}++export function longFlag(name: string): string {+ return `--${kebabCase(name)}`+}+export function optionFlags(name: string, spec: OptionSpec): string {- const long = `--${kebabCase(name)}`+ const long = longFlag(name)const flag = spec.type === 'string' ? `${long} <${spec.placeholder ?? kebabCase(name)}>` : longreturn spec.short ? `-${spec.short}, ${flag}` : flag}diff --git a/hog/src/core/config.ts b/hog/src/core/config.tsindex e5ffa4f002b2..7cea1bbefc1a 100644--- a/hog/src/core/config.ts+++ b/hog/src/core/config.ts@@ -1,6 +1,8 @@import { dirname, join } from 'node:path'import { z } from 'zod'+import { HostSchema } from '@/posthog/host'+import { HogError } from './errors'import type { Runtime } from './runtime'@@ -69,8 +71,7 @@ export type SchemaLanguage = z.infer<typeof SchemaLanguage>export const PostHogConfig = z.strictObject({$schema: z.string().optional().describe('The JSON schema for this file.'),- host: z- .url()+ host: HostSchema.meta({ format: 'uri' }).optional().describe('The PostHog host for this project, like https://eu.posthog.com. `hog auth login` uses it, and other commands stop when your credentials are for another host. --host and HOG_HOST override it.'diff --git a/hog/src/core/globals.test.ts b/hog/src/core/globals.test.tsindex 10d07cb79424..ff1b9c98cc33 100644--- a/hog/src/core/globals.test.ts+++ b/hog/src/core/globals.test.ts@@ -101,6 +101,7 @@ describe('global options', () => {test.each([['an env flag that is not a boolean', ['endpoints', 'list'], { HOG_DEBUG: 'maybe' }],['a rate limit that is not a number', ['endpoints', 'list'], { HOG_RATE_LIMIT: 'fast' }],+ ['a host with a password in it', ['endpoints', 'list'], { HOG_HOST: 'https://user:[email protected]' }],])('%s is a usage error', async (_name, argv, env) => {const result = await runHog(argv, { env: { ...AGENT, ...TEST_CREDENTIALS, ...env } })expect(result.exitCode).toBe(2)diff --git a/hog/src/core/globals.ts b/hog/src/core/globals.tsindex 22364da567de..bd930aefaf00 100644--- a/hog/src/core/globals.ts+++ b/hog/src/core/globals.ts@@ -1,16 +1,33 @@-import type { OptionSpec, OptionValues } from './command'+import { z } from 'zod'++import { parseHost } from '@/posthog/host'++import { longFlag, parseOption, type OptionSpec, type OptionValues } from './command'import type { PostHogConfig } from './config'import { EXIT_USAGE, HogError } from './errors'import type { Env, Runtime, RuntimeFetch } from './runtime'-import { kebabCase } from './text'+import { parseOrThrow, type ParseFailure } from './schema'// Options every command takes. Each one also reads the env vars in `env`, in order, and some read// the posthog.json key at the `config` path. A flag beats an env var, which beats posthog.json.+const RateLimitSchema = z+ .string()+ .regex(/^[1-9]\d*$/, {+ error: (issue) =>+ `The rate limit must be a whole number of requests per minute, but it is "${String(issue.input)}".`,+ })+ .transform(Number)++function parseRateLimit(raw: unknown, failure: ParseFailure): number {+ return parseOrThrow(RateLimitSchema, raw, failure)+}+export const GLOBAL_OPTIONS = {host: {type: 'string',placeholder: 'url',env: ['HOG_HOST'],+ parse: parseHost,description: 'The PostHog host to use instead of the one in your credentials',},dotenvFile: {@@ -62,6 +79,7 @@ export const GLOBAL_OPTIONS = {placeholder: 'requests',env: ['HOG_RATE_LIMIT'],config: 'cli.rateLimit',+ parse: parseRateLimit,description: 'The most requests hog sends per minute',},} as const satisfies Record<string, OptionSpec>@@ -131,7 +149,7 @@ export function resolveGlobals(for (const [name, spec] of Object.entries(GLOBAL_OPTIONS) as [string, OptionSpec][]) {const envNames = spec.env ?? []let value: unknown = flags[name]- let source = `--${kebabCase(name)}`+ let source = longFlag(name)if (value === undefined && spec.type === 'boolean' && spec.lenient) {value = optOutFlag(env, envNames)} else if (value === undefined && spec.type === 'boolean') {@@ -155,18 +173,9 @@ export function resolveGlobals(EXIT_USAGE)}- resolved[name] = value- }- const globals = resolved as GlobalOptions- if (globals.rateLimit !== undefined && !/^[1-9]\d*$/.test(globals.rateLimit)) {- throw new HogError(- 'invalid_setting',- `The rate limit must be a whole number of requests per minute, but it is "${globals.rateLimit}".`,- undefined,- EXIT_USAGE- )+ resolved[name] = parseOption(spec, value, source, 'invalid_setting')}- return globals+ return resolved as GlobalOptions}const WINDOW_MS = 60_000@@ -175,7 +184,7 @@ export function networkRuntime(runtime: Runtime, globals: GlobalOptions): Runtimif (globals.skipSslVerification) {runtime.skipTlsVerification()}- const limit = globals.rateLimit === undefined ? undefined : Number(globals.rateLimit)+ const limit = globals.rateLimitif (limit === undefined && !globals.debug) {return runtime}diff --git a/hog/src/posthog/access-key.ts b/hog/src/posthog/access-key.tsindex 880aa72b4067..863e2abc91b2 100644--- a/hog/src/posthog/access-key.ts+++ b/hog/src/posthog/access-key.ts@@ -5,9 +5,11 @@ import type { Runtime } from '@/core/runtime'import type { StoreChoice, StoredSecret } from '@/posthog/credential-store/types'import { sendRequest } from './api'-import { hostUrl } from './host'+import { hostUrl, type Host } from './host'+import type { ProjectId } from './ids'import { OAuthLogin } from './oauth'import type { LoginRecord } from './settings'+import type { BearerToken, PersonalApiKey } from './tokens'// What `hog auth status` shows about a key.export interface AccessKeyStatus {@@ -36,10 +38,10 @@ export interface AccessKeyStorage {// A key hog sends to PostHog. Each kind owns how it authenticates, renews, logs out and is stored,// so callers never branch on the kind.export interface AccessKey {- readonly host: string- readonly projectId: string+ readonly host: Host+ readonly projectId: ProjectId// What PostHog takes as the bearer token.- readonly token: string+ readonly token: BearerToken// Stays the same for the whole login, unlike an OAuth token, which changes on each renewal.readonly loginKey: string// A key with time left, renewed if it is about to expire, or if it is still `rejectedToken`,@@ -59,20 +61,20 @@ export interface AccessKey {const KEY_CHECK_TIMEOUT_MS = 30_000export class PersonalAPIKey implements AccessKey {- readonly host: string- readonly projectId: string- readonly apiKey: string+ readonly host: Host+ readonly projectId: ProjectId+ readonly apiKey: PersonalApiKey// Null until `verify` asks PostHog, because only PostHog knows a key's scopes.readonly scopes: string[] | null- constructor(fields: { host: string; projectId: string; apiKey: string; scopes?: string[] }) {+ constructor(fields: { host: Host; projectId: ProjectId; apiKey: PersonalApiKey; scopes?: string[] }) {this.host = fields.hostthis.projectId = fields.projectIdthis.apiKey = fields.apiKeythis.scopes = fields.scopes ?? null}- get token(): string {+ get token(): PersonalApiKey {return this.apiKey}diff --git a/hog/src/posthog/api-tools.ts b/hog/src/posthog/api-tools.tsindex 566ac12afb3f..04027f14cc44 100644--- a/hog/src/posthog/api-tools.ts+++ b/hog/src/posthog/api-tools.ts@@ -8,10 +8,11 @@ import type {} from '@posthog/mcp/src/cli/library-types'import type { Context } from '@/core/context'-import { EXIT_USAGE, HogError } from '@/core/errors'+import { HogError } from '@/core/errors'import { VERSION } from '@/version'import { ApiError } from './api'+import type { OrganizationId, ProjectId } from './ids'export interface ToolGroup {slug: string@@ -95,19 +96,12 @@ export function toolRow(library: ApiToolLibrary, tool: ApiToolSummary, granted:}}-export async function apiConnection(- ctx: Context,- scope: { projectId?: string | undefined; organizationId?: string | undefined } = {}-): Promise<ApiConnection> {- // An empty ID, often an unset shell variable, would fall back to another project silently.- for (const [flag, value] of [- ['--project-id', scope.projectId],- ['--organization-id', scope.organizationId],- ] as const) {- if (value !== undefined && value.trim() === '') {- throw new HogError('invalid_input', `${flag} is empty.`, `Pass an ID, or leave out ${flag}.`, EXIT_USAGE)- }- }+interface ConnectionScope {+ projectId?: ProjectId | undefined+ organizationId?: OrganizationId | undefined+}++export async function apiConnection(ctx: Context, scope: ConnectionScope = {}): Promise<ApiConnection> {const session = await ctx.session()const apiKey = await session.token()const key = session.current@@ -126,7 +120,7 @@ export async function apiConnection(// A tool can send several requests, so only a tool that is safe to run twice runs again after a 401.export async function withApiConnection<T>(ctx: Context,- scope: { projectId?: string | undefined; organizationId?: string | undefined },+ scope: ConnectionScope,canRunTwice: boolean,call: (connection: ApiConnection) => Promise<ApiToolResult<T>>): Promise<ApiToolResult<T>> {diff --git a/hog/src/posthog/credential-store/credential-store.test.ts b/hog/src/posthog/credential-store/credential-store.test.tsindex 2c8eee8aa1b9..46b3c9c0f321 100644--- a/hog/src/posthog/credential-store/credential-store.test.ts+++ b/hog/src/posthog/credential-store/credential-store.test.ts@@ -2,6 +2,8 @@ import { describe, expect, test } from 'bun:test'import { HogError } from '@/core/errors'import type { Secrets } from '@/core/runtime'+import { parseHost } from '@/posthog/host'+import { parseOAuthAccessToken, parseOAuthRefreshToken, parsePersonalApiKey } from '@/posthog/tokens'import { fakeRuntime, type FakeRuntime } from '@/testing'import { FileStore } from './file'@@ -9,14 +11,17 @@ import { KeychainStore } from './keychain'import { MemoryStore } from './memory'import type { CredentialStore, StoredSecret } from './types'-const EU = 'https://eu.posthog.com'-const US = 'https://us.posthog.com'+const EU = parseHost('https://eu.posthog.com')+const US = parseHost('https://us.posthog.com')function secret(apiKey: string): StoredSecret {- return { apiKey }+ return { apiKey: parsePersonalApiKey(apiKey) }}-const US_OAUTH: StoredSecret = { accessToken: 'pha_access', refreshToken: 'phr_refresh' }+const US_OAUTH: StoredSecret = {+ accessToken: parseOAuthAccessToken('pha_access'),+ refreshToken: parseOAuthRefreshToken('phr_refresh'),+}// A keychain that answers after `delayMs` of fake time, or never, or fails the way Bun reports a// denied dialog.@@ -54,7 +59,7 @@ describe('credential stores', () => {await store.write(EU, secret('phx_first'))await store.write(US, US_OAUTH)- await store.write(`${EU}/`, secret('phx_second'))+ await store.write(parseHost(`${EU}/`), secret('phx_second'))expect(await store.read(EU)).toEqual(secret('phx_second'))expect(await store.read(US)).toEqual(US_OAUTH)diff --git a/hog/src/posthog/credential-store/file.ts b/hog/src/posthog/credential-store/file.tsindex 0f9337579f9c..e67bf0725370 100644--- a/hog/src/posthog/credential-store/file.ts+++ b/hog/src/posthog/credential-store/file.ts@@ -1,6 +1,6 @@import { hogFile } from '@/core/paths'import type { Runtime } from '@/core/runtime'-import { hostKey } from '@/posthog/host'+import { hostKey, HostSchema, type Host } from '@/posthog/host'import { parseJson, parseSecret } from './helpers'import type { CredentialStore, StoredSecret } from './types'@@ -31,31 +31,41 @@ export class FileStore implements CredentialStore {: {}}- async hosts(): Promise<string[]> {- return Object.keys(await this.readAll())+ async hosts(): Promise<Host[]> {+ return Object.keys(await this.readAll()).flatMap((key) => HostSchema.safeParse(key).data ?? [])}- async read(host: string): Promise<StoredSecret | undefined> {+ async read(host: Host): Promise<StoredSecret | undefined> {return parseSecret((await this.readAll())[hostKey(host)])}- async write(host: string, secret: StoredSecret): Promise<void> {+ async write(host: Host, secret: StoredSecret): Promise<void> {const all = await this.readAll()all[hostKey(host)] = secretawait this.runtime.writePrivateFile(this.path, JSON.stringify(all, null, 2))}- async remove(host: string): Promise<boolean> {- const all = await this.readAll()+ async remove(host: Host): Promise<boolean> {const key = hostKey(host)- if (!(key in all)) {+ return this.removeKeys((name) => name === key)+ }++ // Removes the entries under a name that isn't a host, such as one an older hog wrote, which+ // `hosts` leaves out.+ async removeUnreadable(): Promise<boolean> {+ return this.removeKeys((name) => HostSchema.safeParse(name).data === undefined)+ }++ private async removeKeys(matches: (name: string) => boolean): Promise<boolean> {+ const all = await this.readAll()+ const kept = Object.fromEntries(Object.entries(all).filter(([name]) => !matches(name)))+ if (Object.keys(kept).length === Object.keys(all).length) {return false}- delete all[key]- if (Object.keys(all).length === 0) {+ if (Object.keys(kept).length === 0) {await this.runtime.removeFile(this.path)} else {- await this.runtime.writePrivateFile(this.path, JSON.stringify(all, null, 2))+ await this.runtime.writePrivateFile(this.path, JSON.stringify(kept, null, 2))}return true}diff --git a/hog/src/posthog/credential-store/helpers.ts b/hog/src/posthog/credential-store/helpers.tsindex 47d968d61494..6b31affe4569 100644--- a/hog/src/posthog/credential-store/helpers.ts+++ b/hog/src/posthog/credential-store/helpers.ts@@ -1,3 +1,7 @@+import { z } from 'zod'++import { OAuthAccessTokenSchema, OAuthRefreshTokenSchema, PersonalApiKeySchema } from '@/posthog/tokens'+import type { StoredSecret } from './types'export function parseJson(text: string): unknown {@@ -8,14 +12,12 @@ export function parseJson(text: string): unknown {}}+const StoredSecretSchema = z.union([+ z.object({ apiKey: PersonalApiKeySchema }),+ z.object({ accessToken: OAuthAccessTokenSchema, refreshToken: OAuthRefreshTokenSchema }),+])+// A stored value hog doesn't recognize, such as one a later version wrote, reads as no login.export function parseSecret(value: unknown): StoredSecret | undefined {- const item = value as Record<string, unknown> | null- if (typeof item?.apiKey === 'string') {- return { apiKey: item.apiKey }- }- if (typeof item?.accessToken === 'string' && typeof item.refreshToken === 'string') {- return { accessToken: item.accessToken, refreshToken: item.refreshToken }- }- return undefined+ return StoredSecretSchema.safeParse(value).data}diff --git a/hog/src/posthog/credential-store/keychain.ts b/hog/src/posthog/credential-store/keychain.tsindex 7b9f3ca5b3d8..b2717af0924a 100644--- a/hog/src/posthog/credential-store/keychain.ts+++ b/hog/src/posthog/credential-store/keychain.ts@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto'import { HogError } from '@/core/errors'import type { Runtime } from '@/core/runtime'-import { hostKey } from '@/posthog/host'+import { hostKey, type Host } from '@/posthog/host'import { parseJson, parseSecret } from './helpers'import type { CredentialStore, StoredSecret } from './types'@@ -76,12 +76,12 @@ export class KeychainStore implements CredentialStore {constructor(private readonly runtime: Runtime) {}- async read(host: string): Promise<StoredSecret | undefined> {+ async read(host: Host): Promise<StoredSecret | undefined> {const value = await keychainCall(this.runtime, () => this.runtime.secrets.get(hostKey(host)))return value === null ? undefined : parseSecret(parseJson(value))}- async write(host: string, secret: StoredSecret, options: { removeIfLate?: boolean } = {}): Promise<void> {+ async write(host: Host, secret: StoredSecret, options: { removeIfLate?: boolean } = {}): Promise<void> {const name = hostKey(host)await keychainCall(this.runtime,@@ -90,7 +90,7 @@ export class KeychainStore implements CredentialStore {)}- async remove(host: string): Promise<boolean> {+ async remove(host: Host): Promise<boolean> {return keychainCall(this.runtime, () => this.runtime.secrets.delete(hostKey(host)))}}diff --git a/hog/src/posthog/credential-store/memory.ts b/hog/src/posthog/credential-store/memory.tsindex 75dd18cc3fed..03674a2cecea 100644--- a/hog/src/posthog/credential-store/memory.ts+++ b/hog/src/posthog/credential-store/memory.ts@@ -1,4 +1,4 @@-import { hostKey, type HostKey } from '@/posthog/host'+import { hostKey, type Host, type HostKey } from '@/posthog/host'import type { CredentialStore, StoredSecret } from './types'@@ -7,15 +7,15 @@ export class MemoryStore implements CredentialStore {readonly path = nullprivate readonly items = new Map<HostKey, StoredSecret>()- async read(host: string): Promise<StoredSecret | undefined> {+ async read(host: Host): Promise<StoredSecret | undefined> {return this.items.get(hostKey(host))}- async write(host: string, secret: StoredSecret): Promise<void> {+ async write(host: Host, secret: StoredSecret): Promise<void> {this.items.set(hostKey(host), secret)}- async remove(host: string): Promise<boolean> {+ async remove(host: Host): Promise<boolean> {return this.items.delete(hostKey(host))}}diff --git a/hog/src/posthog/credential-store/types.ts b/hog/src/posthog/credential-store/types.tsindex 3206c35ca5af..91396ea8522d 100644--- a/hog/src/posthog/credential-store/types.ts+++ b/hog/src/posthog/credential-store/types.ts@@ -1,12 +1,17 @@+import { z } from 'zod'++import type { Host } from '@/posthog/host'+import type { OAuthAccessToken, OAuthRefreshToken, PersonalApiKey } from '@/posthog/tokens'+// The part of a login the credential store keeps. settings.json keeps the rest, so a keychain item// stays small however many scopes a login gains.export interface PersonalAPIKeySecret {- apiKey: string+ apiKey: PersonalApiKey}export interface OAuthSecret {- accessToken: string- refreshToken: string+ accessToken: OAuthAccessToken+ refreshToken: OAuthRefreshToken}export type StoredSecret = PersonalAPIKeySecret | OAuthSecret@@ -14,17 +19,19 @@ export type StoredSecret = PersonalAPIKeySecret | OAuthSecretexport type StoreKind = 'keychain' | 'file' | 'memory'// The stores a login can use. The memory store exists for tests only.-export type StoreChoice = Exclude<StoreKind, 'memory'>+export const StoreChoiceSchema = z.enum(['keychain', 'file'])++export type StoreChoice = z.output<typeof StoreChoiceSchema>// Where hog keeps the secrets of the logins `hog auth login` saves, one per host.export interface CredentialStore {readonly kind: StoreKind// The file that holds the secrets. Null for a store that isn't a file.readonly path: string | null- read(host: string): Promise<StoredSecret | undefined>+ read(host: Host): Promise<StoredSecret | undefined>// `removeIfLate` is for a caller that stops using this store when the write times out: a write// that still lands afterwards is removed again, so no item outlives what settings.json records.- write(host: string, secret: StoredSecret, options?: { removeIfLate?: boolean }): Promise<void>+ write(host: Host, secret: StoredSecret, options?: { removeIfLate?: boolean }): Promise<void>// Resolves to false when the store held nothing for the host.- remove(host: string): Promise<boolean>+ remove(host: Host): Promise<boolean>}diff --git a/hog/src/posthog/credentials.test.ts b/hog/src/posthog/credentials.test.tsindex eaaec007eeb7..ac0c97682721 100644--- a/hog/src/posthog/credentials.test.ts+++ b/hog/src/posthog/credentials.test.ts@@ -4,6 +4,7 @@ import { HogError } from '@/core/errors'import { fakeRuntime } from '@/testing'import { DEFAULT_HOST, resolveCredentials } from './credentials'+import { parseHost, type Host } from './host'const ENV = { HOG_PERSONAL_API_KEY: 'phx_env', HOG_PROJECT_ID: '1', HOG_HOST: 'https://env.example.com' }const DOTENV = 'HOG_PERSONAL_API_KEY="phx_dotenv"\n# comment\nHOG_PROJECT_ID=2\n'@@ -13,6 +14,13 @@ const SETTINGS_FILE = '/home/test/.config/hog/settings.json'const EU = 'https://eu.posthog.com'const US = 'https://us.posthog.com'+function parsedHosts(options: { host?: string; configHost?: string }): { host?: Host; configHost?: Host } {+ return {+ host: options.host === undefined ? undefined : parseHost(options.host),+ configHost: options.configHost === undefined ? undefined : parseHost(options.configHost),+ }+}+// What the store keeps for a login: only its secret.function login(apiKey: string): string {return JSON.stringify({ apiKey })@@ -183,8 +191,8 @@ describe('resolveCredentials', () => {'host_mismatch',],] as const)('%s', async (_name, files, keychain, options, expected) => {- const outcome = await resolveCredentials(fakeRuntime({ files, keychain }), options).catch((error: unknown) =>- error instanceof HogError ? error.code : error+ const outcome = await resolveCredentials(fakeRuntime({ files, keychain }), parsedHosts(options)).catch(+ (error: unknown) => (error instanceof HogError ? error.code : error))if (typeof expected === 'string') {expect(outcome).toBe(expected)diff --git a/hog/src/posthog/credentials.ts b/hog/src/posthog/credentials.tsindex d6499e68d079..734f073fcdca 100644--- a/hog/src/posthog/credentials.ts+++ b/hog/src/posthog/credentials.ts@@ -6,11 +6,13 @@ import type { StoreChoice } from '@/posthog/credential-store/types'import { loginStorage, readLogin } from '@/posthog/login/stored'import { PersonalAPIKey, type AccessKey, type AccessKeyStorage } from './access-key'-import { hostKey, sameHost } from './host'+import { hostKey, parseHost, type Host } from './host'+import { parseProjectId } from './ids'import { readSettings } from './settings'+import { parsePersonalApiKey } from './tokens'// posthog-cli falls back to this host when neither --host nor the credentials name one.-export const DEFAULT_HOST = 'https://us.i.posthog.com'+export const DEFAULT_HOST = parseHost('https://us.i.posthog.com')export type Credentials = { key: AccessKey } & (| { source: 'env' }@@ -107,46 +109,6 @@ export function posthogFile(runtime: Runtime, name: string): string {return join(home, name)}-export function checkApiKey(apiKey: string): string | undefined {- return apiKey.startsWith('phx_') ? undefined : "The personal API key doesn't look right: it must start with 'phx_'."-}--export function checkProjectId(projectId: string): string | undefined {- return /^\d+$/.test(projectId) ? undefined : `The project ID must be a number, but it is "${projectId}".`-}--function sameOrigin(a: string, b: string): boolean {- return URL.canParse(a) && URL.canParse(b) && new URL(a).origin === new URL(b).origin-}--export function checkHost(host: string): string | undefined {- return URL.canParse(host) ? undefined : `The host must be a valid URL, but it is "${host}".`-}--function validate(raw: RawCredentials, host: string): PersonalAPIKey {- const keyError = checkApiKey(raw.apiKey)- if (keyError) {- throw new HogError(- 'invalid_credentials',- keyError,- 'Create a personal API key in PostHog under Settings > Personal API keys.'- )- }- const projectError = checkProjectId(raw.projectId)- if (projectError) {- throw new HogError(- 'invalid_credentials',- projectError,- 'Use the number in your project URL, like the 2 in https://us.posthog.com/project/2.'- )- }- const hostError = checkHost(host)- if (hostError) {- throw new HogError('invalid_credentials', hostError)- }- return new PersonalAPIKey({ host, projectId: raw.projectId, apiKey: raw.apiKey })-}-// Every credential source, in order: HOG_PERSONAL_API_KEY in the environment, then in --dotenv-file,// then what `hog auth login` stored. The global host overrides the host a key in the environment// or --dotenv-file carried, and picks which stored login to use. posthog.json comes from the repository, so its host never@@ -156,11 +118,11 @@ export async function resolveCredentials(runtime: Runtime,// `skipStore` leaves out what `hog auth login` stored, for callers that must never open the// keychain or renew a token, like telemetry for a command that needed no credentials.- options: { host?: string; dotenvFile?: string; configHost?: string; skipStore?: boolean }+ options: { host?: Host; dotenvFile?: string; configHost?: Host; skipStore?: boolean }): Promise<Credentials> {- const checkConfigHost = (host: string): void => {+ const checkConfigHost = (host: Host): void => {const { configHost } = options- if (options.host === undefined && configHost !== undefined && !sameOrigin(configHost, host)) {+ if (options.host === undefined && configHost !== undefined && hostKey(configHost) !== hostKey(host)) {throw new HogError('host_mismatch',`posthog.json sets the host to ${configHost}, but your credentials are for ${host}.`,@@ -170,9 +132,14 @@ export async function resolveCredentials(}}const keyFrom = (raw: RawCredentials): PersonalAPIKey => {- const host = options.host ?? raw.host ?? DEFAULT_HOST+ const failure = { code: 'invalid_credentials' }+ const host = options.host ?? (raw.host === undefined ? DEFAULT_HOST : parseHost(raw.host, failure))checkConfigHost(host)- return validate(raw, host)+ return new PersonalAPIKey({+ host,+ projectId: parseProjectId(raw.projectId, failure),+ apiKey: parsePersonalApiKey(raw.apiKey, failure),+ })}const fromEnv = fromLookup((name) => runtime.env[name] || undefined)@@ -218,7 +185,7 @@ export async function resolveCredentials(// Before a renewal, so hog never renews a key it then refuses to send.checkConfigHost(login.key.host)// Logins are kept per origin, so another path on it is another PostHog the login isn't for.- if (options.host !== undefined && !sameHost(options.host, login.key.host)) {+ if (options.host !== undefined && options.host !== login.key.host) {throw new HogError('host_mismatch',`Your login for ${hostKey(options.host)} is for ${login.key.host}, not ${options.host}.`,diff --git a/hog/src/posthog/device-auth.ts b/hog/src/posthog/device-auth.tsindex 8868daf86968..25df43731cd2 100644--- a/hog/src/posthog/device-auth.ts+++ b/hog/src/posthog/device-auth.ts@@ -3,7 +3,8 @@ import { HogError } from '@/core/errors'import { escapeControls } from '@/core/output'import type { Runtime } from '@/core/runtime'-import { hostKey, hostUrl } from './host'+import { hostKey, hostUrl, type Host } from './host'+import { parseProjectId } from './ids'import { HOG_CLIENT_ID, OAuthLogin, oauthPost, type TokenResponse } from './oauth'const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code'@@ -86,14 +87,14 @@ export const READ_ONLY_LOGIN_SCOPES: readonly string[] = [// A login the person still has to approve in the browser. `deviceCode` redeems the tokens once// they approve, so it stays in a private file and never reaches the output.export interface PendingLogin extends PendingApproval {- host: string+ host: HostdeviceCode: stringuserCode: stringscopes: string[]}// PostHog refuses a client it hasn't verified with `unauthorized_client`, and its description says why.-function unauthorizedClient(host: string, body: { error?: string; error_description?: unknown }): HogError | undefined {+function unauthorizedClient(host: Host, body: { error?: string; error_description?: unknown }): HogError | undefined {if (body.error !== 'unauthorized_client' || typeof body.error_description !== 'string') {return undefined}@@ -115,8 +116,8 @@ interface DeviceAuthorizationResponse {// hog opens the approval page only on the host it logs in to. A server that names another origin could// send the person to a look-alike page, and the code check wouldn't catch it: that server chose the code.-function approvalUrl(host: string, userCode: string, named: string): string {- if (URL.canParse(named) && hostKey(named) === hostKey(host)) {+function approvalUrl(host: Host, userCode: string, named: string): string {+ if (URL.canParse(named) && new URL(named).origin === hostKey(host)) {return named}const url = hostUrl(host, 'device')@@ -124,11 +125,7 @@ function approvalUrl(host: string, userCode: string, named: string): string {return url.toString()}-export async function startDeviceLogin(- runtime: Runtime,- host: string,- scopes: readonly string[]-): Promise<PendingLogin> {+export async function startDeviceLogin(runtime: Runtime, host: Host, scopes: readonly string[]): Promise<PendingLogin> {const response = await oauthPost(runtime, host, 'oauth/device-authorization/', {client_id: HOG_CLIENT_ID,scope: scopes.join(' '),@@ -185,8 +182,8 @@ export async function pollDeviceLogin(}const body = (response.json ?? {}) as TokenResponse & { error?: string; error_description?: unknown }if (response.ok) {- const projectId = body.scoped_teams?.[0]- if (projectId === undefined || !body.refresh_token) {+ const scopedTeam = body.scoped_teams?.[0]+ if (scopedTeam === undefined || !body.refresh_token) {throw new HogError('unexpected_response','PostHog approved the login, but its answer had no project or no refresh token.',@@ -197,8 +194,10 @@ export async function pollDeviceLogin(state: 'approved',value: OAuthLogin.fromTokens(runtime, body, {host: pending.host,- projectId: String(projectId),- refreshToken: body.refresh_token,+ projectId: parseProjectId(scopedTeam, {+ code: 'unexpected_response',+ hint: 'Run `hog auth login` to start again.',+ }),scopes: pending.scopes,}),}diff --git a/hog/src/posthog/host.ts b/hog/src/posthog/host.tsindex d4f4fa296ead..415e178df40c 100644--- a/hog/src/posthog/host.ts+++ b/hog/src/posthog/host.ts@@ -43,26 +43,15 @@ export function parseHost(raw: unknown, failure?: Partial<ParseFailure>): Host {return parseOrThrow(HostSchema, raw, { code: 'invalid_host', ...failure })}-// The origin of a PostHog host: its scheme, host name and port, without a path or a trailing-// slash, so `https://eu.posthog.com/` and `https://eu.posthog.com` are the same login. Only-// `hostKey` makes one, so every map of logins uses the same form.-export type HostKey = string & { readonly __brand: 'HostKey' }+// The origin of a host, without its path: its scheme, host name and port. Every map of logins is+// keyed by it. Only `hostKey` makes one.+export type HostKey = string & z.$brand<'HostKey'>-export function hostKey(host: string): HostKey {- return (URL.canParse(host) ? new URL(host).origin : host) as HostKey-}--export function trimHost(host: string): string {- return host.replace(/\/+$/, '')-}--// The same origin and the same path, however each is written.-export function sameHost(a: string, b: string): boolean {- const path = (host: string): string => (URL.canParse(host) ? new URL(host).pathname.replace(/\/+$/, '') : '')- return hostKey(a) === hostKey(b) && path(a) === path(b)+export function hostKey(host: Host): HostKey {+ return new URL(host).origin as HostKey}// Keeps the path a self-hosted PostHog can sit under, such as https://example.com/posthog.-export function hostUrl(host: string, path: string): URL {- return new URL(path, `${trimHost(host)}/`)+export function hostUrl(host: Host, path: string): URL {+ return new URL(path, `${host}/`)}diff --git a/hog/src/posthog/key-session.ts b/hog/src/posthog/key-session.tsindex 6213b2b857ce..085b7baf98df 100644--- a/hog/src/posthog/key-session.ts+++ b/hog/src/posthog/key-session.ts@@ -1,6 +1,7 @@import type { Runtime } from '@/core/runtime'import type { AccessKey, AccessKeyStorage } from './access-key'+import type { BearerToken } from './tokens'// A command can outlive an OAuth access token, so each request renews it first when it is about to// expire, and renews it and sends once more when PostHog answers 401. PostHog checks the token@@ -21,7 +22,7 @@ export class KeySession {return this.key}- async token(): Promise<string> {+ async token(): Promise<BearerToken> {if (this.storage) {this.key = await this.key.fresh(this.runtime, this.storage)}diff --git a/hog/src/posthog/login/flow.ts b/hog/src/posthog/login/flow.tsindex 82f26fc7ce02..49dcff03b22e 100644--- a/hog/src/posthog/login/flow.ts+++ b/hog/src/posthog/login/flow.ts@@ -7,6 +7,8 @@ import { probeKeychain } from '@/posthog/credential-store/keychain'import { openStore } from '@/posthog/credential-store/open'import type { StoreChoice } from '@/posthog/credential-store/types'import { pollDeviceLogin, startDeviceLogin, type PendingLogin } from '@/posthog/device-auth'+import type { Host } from '@/posthog/host'+import type { ProjectId } from '@/posthog/ids'import { withLoginLock, type OAuthLogin } from '@/posthog/oauth'import { loginFor, readSettings } from '@/posthog/settings'@@ -15,8 +17,8 @@ import { writeLogin } from './stored'export const LOGIN_COMMAND = 'hog auth login'export interface LoggedIn {- host: string- projectId: string+ host: Host+ projectId: ProjectIdstore: StoreChoice// Set when the credentials are in a file.credentialsPath: string | null@@ -38,7 +40,7 @@ export function loginWait(runtime: Runtime): ApprovalWait<PendingLogin, OAuthLog// already shared keeps working.export function loginFlow(runtime: Runtime,- host: string,+ host: Host,scopes: readonly string[]): ApprovalFlow<PendingLogin, OAuthLogin> {return {diff --git a/hog/src/posthog/login/stored.test.ts b/hog/src/posthog/login/stored.test.tsindex 39e3fefd5f7b..e75291904cbd 100644--- a/hog/src/posthog/login/stored.test.ts+++ b/hog/src/posthog/login/stored.test.ts@@ -2,15 +2,18 @@ import { describe, expect, test } from 'bun:test'import { PersonalAPIKey } from '@/posthog/access-key'import { FileStore } from '@/posthog/credential-store/file'+import { parseHost, type Host } from '@/posthog/host'+import { parseProjectId } from '@/posthog/ids'+import { parsePersonalApiKey } from '@/posthog/tokens'import { fakeRuntime } from '@/testing'import { writeLogin } from './stored'-const EU = 'https://eu.posthog.com'-const US = 'https://us.posthog.com'+const EU = parseHost('https://eu.posthog.com')+const US = parseHost('https://us.posthog.com')-function login(host: string, apiKey: string): PersonalAPIKey {- return new PersonalAPIKey({ host, projectId: '42', apiKey })+function login(host: Host, apiKey: string): PersonalAPIKey {+ return new PersonalAPIKey({ host, projectId: parseProjectId('42'), apiKey: parsePersonalApiKey(apiKey) })}describe('writeLogin', () => {diff --git a/hog/src/posthog/login/stored.ts b/hog/src/posthog/login/stored.tsindex 9abefd64788a..12a2f19a6887 100644--- a/hog/src/posthog/login/stored.ts+++ b/hog/src/posthog/login/stored.ts@@ -5,7 +5,7 @@ import { accessKeyFromStorage, type AccessKey, type AccessKeyStorage, type Logouimport { FileStore } from '@/posthog/credential-store/file'import { KeychainStore } from '@/posthog/credential-store/keychain'import { openStore } from '@/posthog/credential-store/open'-import { hostKey, type HostKey } from '@/posthog/host'+import { hostKey, type Host, type HostKey } from '@/posthog/host'import { withLoginLock } from '@/posthog/oauth'import { loginFor, readSettings, withLogin, writeSettings, type HogSettings } from '@/posthog/settings'@@ -19,7 +19,7 @@ export interface LoggedOut extends LogoutOutcome {}export interface LoggedOutHost extends LoggedOut {- host: string+ host: Host}export interface StoredLogin {@@ -27,11 +27,7 @@ export interface StoredLogin {store: KeychainStore | FileStore}-export async function readLogin(- runtime: Runtime,- settings: HogSettings,- host: string-): Promise<StoredLogin | undefined> {+export async function readLogin(runtime: Runtime, settings: HogSettings, host: Host): Promise<StoredLogin | undefined> {const record = loginFor(settings, host)if (!record) {return undefined@@ -73,7 +69,7 @@ export async function writeLogin(}// Resolves to false when the store held nothing for the host.-export async function removeLogin(runtime: Runtime, host: string, store: KeychainStore | FileStore): Promise<boolean> {+export async function removeLogin(runtime: Runtime, host: Host, store: KeychainStore | FileStore): Promise<boolean> {return withFileLock(runtime, LOGINS_LOCK, async () => {const removed = await store.remove(host)const settings = withLogin(await readSettings(runtime), host, undefined)@@ -87,18 +83,26 @@ export async function removeLogin(runtime: Runtime, host: string, store: Keychai// stored copy. Resolves to undefined when hog had no login to remove.// Under the renewal lock, so a renewal in another hog process can neither restore the login after// this removes it, nor rotate the refresh token this revokes.-export async function logout(runtime: Runtime, host: string): Promise<LoggedOut | undefined> {+export async function logout(runtime: Runtime, host: Host): Promise<LoggedOut | undefined> {return withLoginLock(runtime, host, async () => {const settings = await readSettings(runtime)const record = loginFor(settings, host)const login = await readLogin(runtime, settings, host)if (!login) {- // The file entry can be gone while the record still names a keychain item left behind.- if (!record?.keychainLeftover) {+ if (!record) {+ return undefined+ }+ // The store can hold an item hog can't read, such as a key an older hog accepted, and+ // the file entry can be gone while the record still names a keychain item left behind.+ // Both are removed, so logout leaves no secret behind.+ const removed = await removeLogin(runtime, host, openStore(runtime, record.store))+ if (!removed && !record.keychainLeftover) {return undefined}- await removeLogin(runtime, host, openStore(runtime, record.store))- return { revoked: null, revokeUrl: null, keychainLeftover: await removeKeychainLeftover(runtime, host) }+ const leftover = record.keychainLeftover ? await removeKeychainLeftover(runtime, host) : null+ // hog can't revoke an OAuth login it can't read, so logout says the session may still work.+ const revoked = record.type === 'oauth' ? false : null+ return { revoked, revokeUrl: null, keychainLeftover: leftover }}const [outcome, removed] = await Promise.all([login.key.logout(runtime),@@ -113,7 +117,7 @@ export async function logout(runtime: Runtime, host: string): Promise<LoggedOut}// Resolves to why the removal failed, or null once no item is left.-async function removeKeychainLeftover(runtime: Runtime, host: string): Promise<string | null> {+async function removeKeychainLeftover(runtime: Runtime, host: Host): Promise<string | null> {try {await new KeychainStore(runtime).remove(host)return null@@ -124,7 +128,7 @@ async function removeKeychainLeftover(runtime: Runtime, host: string): Promise<s// For a host settings.json names no keychain item for. A machine without a usable keychain can't// hold one, so only a refused or abandoned removal counts as a failure.-async function sweepKeychain(runtime: Runtime, host: string): Promise<{ removed: boolean; error: string | null }> {+async function sweepKeychain(runtime: Runtime, host: Host): Promise<{ removed: boolean; error: string | null }> {try {return { removed: await new KeychainStore(runtime).remove(host), error: null }} catch (error) {@@ -141,7 +145,7 @@ async function sweepKeychain(runtime: Runtime, host: string): Promise<{ removed:export async function logoutAll(runtime: Runtime): Promise<LoggedOutHost[]> {const settings = await readSettings(runtime)const file = new FileStore(runtime)- const hosts = new Map<HostKey, string>()+ const hosts = new Map<HostKey, Host>()const recorded = Object.values(settings.logins ?? {}).flatMap((record) => (record ? [record.host] : []))for (const host of [...recorded, ...(await file.hosts())]) {if (!hosts.has(hostKey(host))) {@@ -163,5 +167,6 @@ export async function logoutAll(runtime: Runtime): Promise<LoggedOutHost[]> {loggedOut.push({ ...base, keychainLeftover: base.keychainLeftover ?? swept.error, host })}}+ await withFileLock(runtime, LOGINS_LOCK, () => file.removeUnreadable())return loggedOut}diff --git a/hog/src/posthog/oauth.test.ts b/hog/src/posthog/oauth.test.tsindex 9873fd27d563..89e3f3fa597e 100644--- a/hog/src/posthog/oauth.test.ts+++ b/hog/src/posthog/oauth.test.ts@@ -7,6 +7,7 @@ import { fakeRuntime, type FakeRuntime } from '@/testing'import { PostHogApi } from './api'import { resolveCredentials, type Credentials } from './credentials'+import { parseHost } from './host'import { KeySession } from './key-session'import { HOG_CLIENT_ID } from './oauth'@@ -228,7 +229,7 @@ describe('OAuth credentials', () => {respond: () => ({ status: 200, body: { access_token: 'pha_new', expires_in: 3600 } }),})- const error = await resolveCredentials(runtime, { configHost: 'https://us.posthog.com' }).catch(+ const error = await resolveCredentials(runtime, { configHost: parseHost('https://us.posthog.com') }).catch((caught: unknown) => caught)diff --git a/hog/src/posthog/oauth.ts b/hog/src/posthog/oauth.tsindex 5a4ae3d44824..af97136a6edf 100644--- a/hog/src/posthog/oauth.ts+++ b/hog/src/posthog/oauth.ts@@ -9,8 +9,10 @@ import type { OAuthSecret, StoreChoice } from '@/posthog/credential-store/types'import type { AccessKey, AccessKeyStatus, AccessKeyStorage, LogoutOutcome } from './access-key'import { sendRequest, type HttpResponse } from './api'-import { hostKey, hostUrl } from './host'+import { hostKey, hostUrl, type Host } from './host'+import type { ProjectId } from './ids'import type { LoginRecord } from './settings'+import { parseOAuthAccessToken, parseOAuthRefreshToken, type OAuthAccessToken, type OAuthRefreshToken } from './tokens'// hog's CIMD client ID: the URL of its client metadata document, which PostHog fetches.export const HOG_CLIENT_ID = 'https://posthog.com/.well-known/oauth/hog/client-metadata.json'@@ -29,7 +31,7 @@ export interface TokenResponse {export function oauthPost(runtime: Runtime,- host: string,+ host: Host,path: string,form: Record<string, string>,timeoutMs = REQUEST_TIMEOUT_MS@@ -42,10 +44,10 @@ export function oauthPost(}interface OAuthLoginFields {- host: string- projectId: string- accessToken: string- refreshToken: string+ host: Host+ projectId: ProjectId+ accessToken: OAuthAccessToken+ refreshToken: OAuthRefreshToken// Epoch milliseconds after which the access token stops working.expiresAt: numberscopes: string[]@@ -55,7 +57,7 @@ interface OAuthLoginFields {}// Serializes the processes that renew or remove the login to one host.-export function withLoginLock<T>(runtime: Runtime, host: string, work: () => Promise<T>): Promise<T> {+export function withLoginLock<T>(runtime: Runtime, host: Host, work: () => Promise<T>): Promise<T> {// By origin, so `https://eu.posthog.com/` and `https://eu.posthog.com` take the same lock.const name = createHash('sha256').update(hostKey(host)).digest('hex').slice(0, 16)return withFileLock(runtime, `refresh-${name}.lock`, work)@@ -63,10 +65,10 @@ export function withLoginLock<T>(runtime: Runtime, host: string, work: () => Pro// What `hog auth login` gets from the OAuth device grant. The access token works in one project.export class OAuthLogin implements AccessKey {- readonly host: string- readonly projectId: string- readonly accessToken: string- readonly refreshToken: string+ readonly host: Host+ readonly projectId: ProjectId+ readonly accessToken: OAuthAccessToken+ readonly refreshToken: OAuthRefreshTokenreadonly expiresAt: numberreadonly scopes: string[]readonly loginId: string@@ -86,7 +88,10 @@ export class OAuthLogin implements AccessKey {static fromTokens(runtime: Runtime,body: TokenResponse,- previous: Pick<OAuthLoginFields, 'host' | 'projectId' | 'refreshToken' | 'scopes'> & { loginId?: string }+ previous: Pick<OAuthLoginFields, 'host' | 'projectId' | 'scopes'> & {+ refreshToken?: OAuthRefreshToken+ loginId?: string+ }): OAuthLogin {if (!body.access_token || body.expires_in === undefined) {throw new HogError(@@ -95,18 +100,19 @@ export class OAuthLogin implements AccessKey {'Run `hog auth login` to log in again.')}+ const unexpected = { code: 'unexpected_response' }return new OAuthLogin({host: previous.host,projectId: previous.projectId,- accessToken: body.access_token,- refreshToken: body.refresh_token ?? previous.refreshToken,+ accessToken: parseOAuthAccessToken(body.access_token, unexpected),+ refreshToken: parseOAuthRefreshToken(body.refresh_token ?? previous.refreshToken, unexpected),expiresAt: runtime.now() + body.expires_in * 1000,scopes: body.scope ? body.scope.split(' ').filter(Boolean) : previous.scopes,loginId: previous.loginId ?? randomUUID(),})}- get token(): string {+ get token(): OAuthAccessToken {return this.accessToken}diff --git a/hog/src/posthog/settings.ts b/hog/src/posthog/settings.tsindex 25a3c0970a01..28fc28172b10 100644--- a/hog/src/posthog/settings.ts+++ b/hog/src/posthog/settings.ts@@ -1,34 +1,45 @@+import { z } from 'zod'+import { hogFile } from '@/core/paths'import type { Runtime } from '@/core/runtime'-import type { StoreChoice } from '@/posthog/credential-store/types'+import { StoreChoiceSchema } from '@/posthog/credential-store/types'-import { hostKey, type HostKey } from './host'+import { hostKey, HostSchema, type Host, type HostKey } from './host'+import { ProjectIdSchema } from './ids'-// What settings.json keeps about the login to one host: everything except its secrets.-interface LoginRecordBase {+const LoginRecordBaseSchema = z.object({// hog probes the keychain only at login, because a probe can open a dialog. Each host keeps its// own answer, so a login over SSH that had to use the file doesn't hide a keychain login to// another host.- store: StoreChoice- projectId: string+ store: StoreChoiceSchema,+ projectId: ProjectIdSchema,// The host the login was made for, with the path a self-hosted PostHog sits under. The login is// keyed by origin, so a posthog.json path on the same origin can't send it elsewhere.- host: string+ host: HostSchema,// Set on a file login that replaced a keychain login while the keychain was unusable, so the old// keychain item can still be there. Logout tries to remove it.- keychainLeftover?: true-}+ keychainLeftover: z.boolean().optional(),+})++// What settings.json keeps about the login to one host: everything except its secrets.+const LoginRecordSchema = z.discriminatedUnion('type', [+ LoginRecordBaseSchema.extend({ type: z.literal('personal_api_key') }),+ LoginRecordBaseSchema.extend({+ type: z.literal('oauth'),+ // Epoch milliseconds, for the access token.+ expiresAt: z.number(),+ scopes: z.array(z.string()),+ loginId: z.string(),+ }),+])-export type LoginRecord =- | (LoginRecordBase & { type: 'personal_api_key' })- // `expiresAt` is in epoch milliseconds, for the access token.- | (LoginRecordBase & { type: 'oauth'; expiresAt: number; scopes: string[]; loginId: string })+export type LoginRecord = z.output<typeof LoginRecordSchema>// What `hog auth login` decided, kept so later runs don't decide again. Nothing in it is secret.export interface HogSettings {logins?: Partial<Record<HostKey, LoginRecord>>// The host of the last login, which commands use when neither --host nor posthog.json names one.- host?: string+ host?: Host}const SETTINGS_FILE = 'settings.json'@@ -37,34 +48,12 @@ function settingsPath(runtime: Runtime): string {return hogFile(runtime, SETTINGS_FILE)}-// A record hog doesn't recognize, such as one a later version wrote, reads as no login.+// A record hog doesn't recognize, such as one a later version wrote, reads as no login. So does a+// record filed under another origin than its own host.function parseLoginRecord(origin: string, value: unknown): LoginRecord | undefined {- const item = value as Record<string, unknown> | null- if (- (item?.store !== 'keychain' && item?.store !== 'file') ||- typeof item.projectId !== 'string' ||- typeof item.host !== 'string' ||- hostKey(item.host) !== hostKey(origin)- ) {- return undefined- }- const { store, projectId, host } = item- const base: LoginRecordBase =- item.keychainLeftover === true ? { store, projectId, host, keychainLeftover: true } : { store, projectId, host }- if (item.type === 'personal_api_key') {- return { ...base, type: 'personal_api_key' }- }- if (- item.type === 'oauth' &&- typeof item.expiresAt === 'number' &&- typeof item.loginId === 'string' &&- Array.isArray(item.scopes) &&- item.scopes.every((scope) => typeof scope === 'string')- ) {- const { expiresAt, loginId } = item- return { ...base, type: 'oauth', expiresAt, scopes: item.scopes, loginId }- }- return undefined+ const record = LoginRecordSchema.safeParse(value).data+ const key = HostSchema.safeParse(origin).data+ return record && key && hostKey(record.host) === hostKey(key) ? record : undefined}// A missing or broken file means hog has no settings yet. Any other read failure stops the command,@@ -91,24 +80,22 @@ export async function readSettings(runtime: Runtime): Promise<HogSettings> {for (const [host, value] of Object.entries(raw.logins)) {const record = parseLoginRecord(host, value)if (record) {- logins[hostKey(host)] = record+ logins[hostKey(record.host)] = record}}}- return {- logins,- host: typeof raw.host === 'string' ? raw.host : undefined,- }+ return { logins, host: HostSchema.safeParse(raw.host).data }}-export function loginFor(settings: HogSettings, host: string): LoginRecord | undefined {+export function loginFor(settings: HogSettings, host: Host): LoginRecord | undefined {return settings.logins?.[hostKey(host)]}// The settings with the login for `host` replaced, or removed when `record` is undefined.-export function withLogin(settings: HogSettings, host: string, record: LoginRecord | undefined): HogSettings {- const { [hostKey(host)]: _previous, ...others } = settings.logins ?? {}- return { ...settings, logins: record ? { ...others, [hostKey(host)]: record } : others }+export function withLogin(settings: HogSettings, host: Host, record: LoginRecord | undefined): HogSettings {+ const key = hostKey(host)+ const { [key]: _previous, ...others } = settings.logins ?? {}+ return { ...settings, logins: record ? { ...others, [key]: record } : others }}export async function writeSettings(runtime: Runtime, settings: HogSettings): Promise<void> {