Skip to content

: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.

feat(hog): parse flags, env vars and stored logins into branded types (#129794)

Rafael Audibertdceeb5c9e935
diff --git a/hog/AGENTS.md b/hog/AGENTS.md
index 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.ts
index 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 = true
diff --git a/hog/src/commands/api/api.test.ts b/hog/src/commands/api/api.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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_HOST
const key = new PersonalAPIKey({ host, projectId, apiKey })
const loggedIn = await saveLogin(runtime, key)
const { store, credentialsPath, keychainError } = loggedIn
diff --git a/hog/src/core/command.ts b/hog/src/core/command.ts
index 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)}>` : long
return spec.short ? `-${spec.short}, ${flag}` : flag
}
diff --git a/hog/src/core/config.ts b/hog/src/core/config.ts
index 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.ts
index 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.ts
index 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): Runtim
if (globals.skipSslVerification) {
runtime.skipTlsVerification()
}
- const limit = globals.rateLimit === undefined ? undefined : Number(globals.rateLimit)
+ const limit = globals.rateLimit
if (limit === undefined && !globals.debug) {
return runtime
}
diff --git a/hog/src/posthog/access-key.ts b/hog/src/posthog/access-key.ts
index 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_000
export 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.host
this.projectId = fields.projectId
this.apiKey = fields.apiKey
this.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.ts
index 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.ts
index 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.ts
index 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)] = secret
await 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.ts
index 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.ts
index 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.ts
index 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 = null
private 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.ts
index 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 | OAuthSecret
export 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.ts
index 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.ts
index 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.ts
index 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: Host
deviceCode: string
userCode: string
scopes: 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.ts
index 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.ts
index 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.ts
index 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: ProjectId
store: 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.ts
index 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.ts
index 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 Logou
import { 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.ts
index 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.ts
index 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: number
scopes: 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: OAuthRefreshToken
readonly expiresAt: number
readonly 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.ts
index 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> {