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): add branded types for hosts, IDs and tokens (#129792)

Rafael Audibert82aba73581da
diff --git a/hog/src/core/schema.ts b/hog/src/core/schema.ts
new file mode 100644
index 000000000000..1ca18b2af489
--- /dev/null
+++ b/hog/src/core/schema.ts
@@ -0,0 +1,42 @@
+import type { z } from 'zod'
+
+import { HogError } from './errors'
+
+export interface ParseFailure {
+ code: string
+ hint?: string
+ context?: string
+ exitCode?: number
+}
+
+const MAX_LISTED_ERRORS = 5
+
+// Every issue zod found, so a person can fix them all in one go. The schemas in hog set their own
+// messages, and an issue inside a document, such as an API answer, starts with its field.
+export function getErrorMessage(error: z.ZodError): string {
+ const messages = error.issues.map((issue) =>
+ issue.path.length > 0 ? `${issue.path.map(String).join('.')}: ${issue.message}` : issue.message
+ )
+ const more = messages.length - MAX_LISTED_ERRORS
+ const listed = messages.slice(0, MAX_LISTED_ERRORS).join('; ')
+ return more > 0 ? `${listed}; and ${more} more` : listed || 'The value is not valid.'
+}
+
+export function validationError(schema: z.ZodType, raw: unknown): string | undefined {
+ const parsed = schema.safeParse(raw)
+ return parsed.success ? undefined : getErrorMessage(parsed.error)
+}
+
+export function parseOrThrow<S extends z.ZodType>(schema: S, raw: unknown, failure: ParseFailure): z.output<S> {
+ const parsed = schema.safeParse(raw)
+ if (parsed.success) {
+ return parsed.data
+ }
+ const message = getErrorMessage(parsed.error)
+ throw new HogError(
+ failure.code,
+ failure.context ? `${failure.context} ${message}` : message,
+ failure.hint,
+ failure.exitCode
+ )
+}
diff --git a/hog/src/posthog/brands.test.ts b/hog/src/posthog/brands.test.ts
new file mode 100644
index 000000000000..145d04dfa120
--- /dev/null
+++ b/hog/src/posthog/brands.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test'
+
+import { HogError } from '@/core/errors'
+
+import { parseHost } from './host'
+import { parseOrganizationId, parseProjectId } from './ids'
+import { parseOAuthAccessToken, parsePersonalApiKey, parseProjectToken, parseWorkloadToken } from './tokens'
+
+function errorOf(parse: () => unknown): string {
+ try {
+ parse()
+ } catch (error) {
+ return error instanceof HogError ? `${error.code}: ${error.message}` : String(error)
+ }
+ return 'parsed'
+}
+
+describe('brand factories', () => {
+ test.each([
+ ['a personal API key', () => parsePersonalApiKey('phx_abc123'), 'parsed'],
+ [
+ 'an OAuth access token as a personal API key',
+ () => parsePersonalApiKey('pha_abc123'),
+ 'invalid_personal_api_key: This is an OAuth access token, not a personal API key, which must start with phx_.',
+ ],
+ [
+ 'a legacy personal API key without a prefix',
+ () => parsePersonalApiKey('a'.repeat(43)),
+ "invalid_personal_api_key: This doesn't look like a personal API key: it must start with phx_.",
+ ],
+ [
+ 'a personal API key copied with a line break',
+ () => parsePersonalApiKey('phx_abc\n'),
+ "invalid_personal_api_key: This token is cut off, or has characters a token can't have, such as a space or a quote. Copy it again.",
+ ],
+ [
+ 'a personal API key as an OAuth access token',
+ () => parseOAuthAccessToken('phx_abc123'),
+ 'invalid_oauth_access_token: This is a personal API key, not an OAuth access token, which must start with pha_.',
+ ],
+ ['a JWT as a workload token', () => parseWorkloadToken('eyJhbGciOi.eyJzdWIiOi.c2lnbmF0dXJl'), 'parsed'],
+ [
+ 'a personal API key as a workload token',
+ () => parseWorkloadToken('phx_abc123'),
+ 'invalid_workload_token: This is a personal API key, not a workload token, which must be a JWT, three parts joined by dots.',
+ ],
+ ['a custom project token without the prefix', () => parseProjectToken('my-team-token'), 'parsed'],
+ ['a custom project token with the prefix and punctuation', () => parseProjectToken('phc_team.v1'), 'parsed'],
+ [
+ 'a personal API key as a project token',
+ () => parseProjectToken('phx_abc123'),
+ 'invalid_project_token: This is a personal API key, not a project token.',
+ ],
+ [
+ 'an organization ID that is not a UUID',
+ () => parseOrganizationId('acme'),
+ "invalid_organization_id: The organization ID must be a UUID. Pass the organization's UUID, like 0188f5b4-1d2a-7000-8a1c-3f6e2b9c7d10.",
+ ],
+ [
+ 'a project ID that is not a number',
+ () => parseProjectId('two', { code: 'invalid_credentials' }),
+ 'invalid_credentials: The project ID must be a number. Pass a numeric project ID, like 12345.',
+ ],
+ [
+ 'a host with a password in it',
+ () => parseHost('https://user:[email protected]'),
+ 'invalid_host: The host must not have a user name or password in it.',
+ ],
+ [
+ 'a host without a scheme',
+ () => parseHost('localhost:8000'),
+ 'invalid_host: The host must start with https:// or http://, like https://us.posthog.com.',
+ ],
+ [
+ 'a host that is not a URL, without repeating its password',
+ () => parseHost('https://user:secret@ph example.com'),
+ 'invalid_host: The host must be a URL, like https://us.posthog.com.',
+ ],
+ [
+ 'a host with a query',
+ () => parseHost('https://eu.posthog.com/?token=secret'),
+ 'invalid_host: The host must not have a query (?) or a fragment (#) in it.',
+ ],
+ ])('%s', (_name, parse, expected) => {
+ expect(errorOf(parse)).toBe(expected)
+ })
+
+ test.each([
+ ['HTTPS://EU.posthog.com:443/', 'https://eu.posthog.com'],
+ ['https://example.com/posthog/', 'https://example.com/posthog'],
+ ])('the host %s is the same login as %s', (raw, expected) => {
+ expect(parseHost(raw)).toBe(parseHost(expected))
+ })
+})
diff --git a/hog/src/posthog/host.ts b/hog/src/posthog/host.ts
index 5ab35ccd3287..d4f4fa296ead 100644
--- a/hog/src/posthog/host.ts
+++ b/hog/src/posthog/host.ts
@@ -1,3 +1,48 @@
+import { z } from 'zod'
+
+import { parseOrThrow, type ParseFailure } from '@/core/schema'
+
+// An http or https origin, plus the path a self-hosted PostHog can sit under. It is normalized, so
+// two ways to write one host compare equal.
+export const HostSchema = z
+ .string({ error: 'The host must be a URL, like https://us.posthog.com.' })
+ .check((ctx) => {
+ const message = validateHost(ctx.value)
+ if (message) {
+ ctx.issues.push({ code: 'custom', input: ctx.value, message, abort: true })
+ }
+ })
+ .overwrite((value) => {
+ const url = new URL(value)
+ return `${url.origin}${url.pathname.replace(/\/+$/, '')}`
+ })
+ .brand<'Host'>()
+
+export type Host = z.output<typeof HostSchema>
+
+// The messages never repeat the value, because it can hold a password or a token in its query.
+function validateHost(value: string): string | undefined {
+ const url = URL.parse(value)
+ if (url === null) {
+ return 'The host must be a URL, like https://us.posthog.com.'
+ }
+ // `localhost:8000` parses with `localhost:` as its scheme, so check what the person typed.
+ if (!/^https?:\/\//i.test(value)) {
+ return 'The host must start with https:// or http://, like https://us.posthog.com.'
+ }
+ if (url.username || url.password) {
+ return 'The host must not have a user name or password in it.'
+ }
+ if (url.search || url.hash) {
+ return 'The host must not have a query (?) or a fragment (#) in it.'
+ }
+ return undefined
+}
+
+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.
diff --git a/hog/src/posthog/ids.ts b/hog/src/posthog/ids.ts
new file mode 100644
index 000000000000..c8fcdc7d2fdc
--- /dev/null
+++ b/hog/src/posthog/ids.ts
@@ -0,0 +1,40 @@
+import { z } from 'zod'
+
+import { parseOrThrow, type ParseFailure } from '@/core/schema'
+
+// PostHog sends a project ID as a number and hog keeps it as text, as it appears in URLs. The
+// messages leave out the value, because a user who pastes a token into the wrong flag would see
+// it in logs.
+const PROJECT_ID_ERROR = 'The project ID must be a number. Pass a numeric project ID, like 12345.'
+
+export const ProjectIdSchema = z
+ .union([z.string(), z.int()], { error: PROJECT_ID_ERROR })
+ .transform(String)
+ .pipe(z.string().regex(/^\d+$/, { error: PROJECT_ID_ERROR }))
+ .brand<'ProjectId'>()
+
+export type ProjectId = z.output<typeof ProjectIdSchema>
+
+export const OrganizationIdSchema = z
+ .guid({
+ error: "The organization ID must be a UUID. Pass the organization's UUID, like 0188f5b4-1d2a-7000-8a1c-3f6e2b9c7d10.",
+ })
+ .brand<'OrganizationId'>()
+
+export type OrganizationId = z.output<typeof OrganizationIdSchema>
+
+export function parseProjectId(raw: unknown, failure?: Partial<ParseFailure>): ProjectId {
+ return parseOrThrow(ProjectIdSchema, raw, {
+ code: 'invalid_project_id',
+ hint: 'Use the number in your project URL, like the 2 in https://us.posthog.com/project/2, or copy it from https://app.posthog.com/settings/project-details',
+ ...failure,
+ })
+}
+
+export function parseOrganizationId(raw: unknown, failure?: Partial<ParseFailure>): OrganizationId {
+ return parseOrThrow(OrganizationIdSchema, raw, {
+ code: 'invalid_organization_id',
+ hint: 'Copy the organization ID from Settings > Organization in PostHog: https://app.posthog.com/settings/organization',
+ ...failure,
+ })
+}
diff --git a/hog/src/posthog/tokens.ts b/hog/src/posthog/tokens.ts
new file mode 100644
index 000000000000..550f37d30fc1
--- /dev/null
+++ b/hog/src/posthog/tokens.ts
@@ -0,0 +1,126 @@
+import { z } from 'zod'
+
+import { parseOrThrow, type ParseFailure } from '@/core/schema'
+
+// What each prefix PostHog issues means, from posthog/models/utils.py. Project secret API keys and
+// team secret tokens share `phs_`, so hog can't tell them apart.
+const KNOWN_PREFIXES: Record<string, string> = {
+ phx_: 'a personal API key',
+ phc_: 'a project token',
+ phs_: 'a secret API key',
+ pha_: 'an OAuth access token',
+ phr_: 'an OAuth refresh token',
+}
+
+// The message never contains the value, which would end up in logs and agent transcripts.
+function tokenError(value: unknown, name: string, rule: string): string {
+ const other = typeof value === 'string' ? KNOWN_PREFIXES[value.slice(0, 4)] : undefined
+ return other
+ ? `This is ${other}, not ${name}, which must ${rule}.`
+ : `This doesn't look like ${name}: it must ${rule}.`
+}
+
+// New tokens are base57 and older ones URL-safe base64, so the part after the prefix fits both.
+function prefixedToken(prefix: string, name: string): z.ZodString {
+ return z.string({ error: 'The token must be text.' }).regex(new RegExp(`^${prefix}[A-Za-z0-9_-]+$`), {
+ error: (issue) =>
+ typeof issue.input === 'string' && issue.input.startsWith(prefix)
+ ? `This token is cut off, or has characters a token can't have, such as a space or a quote. Copy it again.`
+ : tokenError(issue.input, name, `start with ${prefix}`),
+ })
+}
+
+// PostHog also accepts a custom project token, with or without the prefix and with any characters,
+// so only an empty token or one with another kind's prefix fails.
+function projectTokenError(value: string): string | undefined {
+ if (value === '' || value === 'phc_') {
+ return 'The project token is empty.'
+ }
+ const other = value.startsWith('phc_') ? undefined : KNOWN_PREFIXES[value.slice(0, 4)]
+ return other ? `This is ${other}, not a project token.` : undefined
+}
+
+export const PersonalApiKeySchema = prefixedToken('phx_', 'a personal API key').brand<'PersonalApiKey'>()
+export const ProjectSecretApiKeySchema = prefixedToken(
+ 'phs_',
+ 'a project secret API key'
+).brand<'ProjectSecretApiKey'>()
+export const TeamSecretTokenSchema = prefixedToken('phs_', 'a team secret token').brand<'TeamSecretToken'>()
+export const OAuthAccessTokenSchema = prefixedToken('pha_', 'an OAuth access token').brand<'OAuthAccessToken'>()
+export const OAuthRefreshTokenSchema = prefixedToken('phr_', 'an OAuth refresh token').brand<'OAuthRefreshToken'>()
+
+export const ProjectTokenSchema = z
+ .string({ error: 'The token must be text.' })
+ .refine((value) => projectTokenError(value) === undefined, {
+ error: (issue) => projectTokenError(String(issue.input)),
+ })
+ .brand<'ProjectToken'>()
+
+// A workload token is a JWT, which has no PostHog prefix.
+export const WorkloadTokenSchema = z
+ .string({ error: 'The token must be text.' })
+ .regex(/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/, {
+ error: (issue) => tokenError(issue.input, 'a workload token', 'be a JWT, three parts joined by dots'),
+ })
+ .brand<'WorkloadToken'>()
+
+export type PersonalApiKey = z.output<typeof PersonalApiKeySchema>
+export type ProjectToken = z.output<typeof ProjectTokenSchema>
+export type ProjectSecretApiKey = z.output<typeof ProjectSecretApiKeySchema>
+export type TeamSecretToken = z.output<typeof TeamSecretTokenSchema>
+export type OAuthAccessToken = z.output<typeof OAuthAccessTokenSchema>
+export type OAuthRefreshToken = z.output<typeof OAuthRefreshTokenSchema>
+export type WorkloadToken = z.output<typeof WorkloadTokenSchema>
+
+export type BearerToken = PersonalApiKey | OAuthAccessToken
+
+const LOG_IN_AGAIN = 'Run `hog auth login` to log in again.'
+const PROJECT_SETTINGS = 'Copy it again from your project settings: https://app.posthog.com/settings/project-details'
+
+export function parsePersonalApiKey(raw: unknown, failure?: Partial<ParseFailure>): PersonalApiKey {
+ return parseOrThrow(PersonalApiKeySchema, raw, {
+ code: 'invalid_personal_api_key',
+ hint: 'Create a personal API key in PostHog: https://app.posthog.com/settings/user-api-keys',
+ ...failure,
+ })
+}
+
+export function parseProjectToken(raw: unknown, failure?: Partial<ParseFailure>): ProjectToken {
+ return parseOrThrow(ProjectTokenSchema, raw, { code: 'invalid_project_token', hint: PROJECT_SETTINGS, ...failure })
+}
+
+export function parseProjectSecretApiKey(raw: unknown, failure?: Partial<ParseFailure>): ProjectSecretApiKey {
+ return parseOrThrow(ProjectSecretApiKeySchema, raw, {
+ code: 'invalid_project_secret_api_key',
+ hint: PROJECT_SETTINGS,
+ ...failure,
+ })
+}
+
+export function parseTeamSecretToken(raw: unknown, failure?: Partial<ParseFailure>): TeamSecretToken {
+ return parseOrThrow(TeamSecretTokenSchema, raw, {
+ code: 'invalid_team_secret_token',
+ hint: PROJECT_SETTINGS,
+ ...failure,
+ })
+}
+
+export function parseOAuthAccessToken(raw: unknown, failure?: Partial<ParseFailure>): OAuthAccessToken {
+ return parseOrThrow(OAuthAccessTokenSchema, raw, {
+ code: 'invalid_oauth_access_token',
+ hint: LOG_IN_AGAIN,
+ ...failure,
+ })
+}
+
+export function parseOAuthRefreshToken(raw: unknown, failure?: Partial<ParseFailure>): OAuthRefreshToken {
+ return parseOrThrow(OAuthRefreshTokenSchema, raw, {
+ code: 'invalid_oauth_refresh_token',
+ hint: LOG_IN_AGAIN,
+ ...failure,
+ })
+}
+
+export function parseWorkloadToken(raw: unknown, failure?: Partial<ParseFailure>): WorkloadToken {
+ return parseOrThrow(WorkloadTokenSchema, raw, { code: 'invalid_workload_token', ...failure })
+}