: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): add branded types for hosts, IDs and tokens (#129792)
Rafael Audibert82aba73581da
diff --git a/hog/src/core/schema.ts b/hog/src/core/schema.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 })+}