UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

289 lines (260 loc) • 14 kB
/** * Wire contract for the opt-in public profile (leaderboard). Shared by the proxy and the collector * (services/telemetry-collector imports it), like ../contract.ts, so any change here needs a * collector-first rollout. Import-free apart from the anonymous contract's closed rosters. * * Nothing here relates to the anonymous install identity: a profile day carries no install id, * install-day hash, batch id, version, platform, channel, provider kind or error field. */ import { MODEL_FAMILIES, parseCalendarUtcDayMs, type TelemetryModelFamily } from "../contract"; export const PROFILE_SCHEMA_VERSION = 1 as const; export const PROFILE_HANDLE_MIN = 3; export const PROFILE_HANDLE_MAX = 24; export const PROFILE_HANDLE_RE = /^[a-z0-9][a-z0-9-]{1,22}[a-z0-9]$/; export const PROFILE_DISPLAY_NAME_MAX = 32; export const PROFILE_MAX_DAY_REQUESTS = 1_000_000; export const PROFILE_MAX_DAY_TOKENS = 10_000_000_000; export const PROFILE_SUBMIT_MAX_AGE_DAYS = 7; /** `ocxp_` + base64url of 32 random bytes. */ export const PROFILE_SECRET_RE = /^ocxp_[A-Za-z0-9_-]{43}$/; export const PROFILE_RESERVED_HANDLES: readonly string[] = Object.freeze([ "about", "admin", "administrator", "anthropic", "api", "app", "dashboard", "deepseek", "delete", "docs", "everyone", "github", "google", "help", "leaderboard", "lidge", "login", "logout", "me", "mod", "moderator", "new", "null", "ocx", "official", "openai", "opencodex", "owner", "privacy", "profile", "profiles", "rank", "root", "security", "settings", "staff", "stats", "support", "system", "team", "telemetry", "test", "undefined", "xai", ]); export const PROFILE_AVATARS = Object.freeze([ "slate", "red", "orange", "amber", "lime", "green", "teal", "cyan", "blue", "indigo", "violet", "pink", ] as const); export type ProfileAvatar = typeof PROFILE_AVATARS[number]; export const PROFILE_PERIODS = Object.freeze(["day", "week", "month"] as const); export type ProfilePeriod = typeof PROFILE_PERIODS[number]; export const PROFILE_PERIOD_DAYS: Readonly<Record<ProfilePeriod, number>> = Object.freeze({ day: 1, week: 7, month: 30 }); export const PROFILE_METRICS = Object.freeze(["tokens", "requests"] as const); export type ProfileMetric = typeof PROFILE_METRICS[number]; export interface ProfileTokensV1 { input: number; cacheRead: number; cacheWrite: number; output: number; reasoning: number; } export interface ProfileFamilyRowV1 { family: TelemetryModelFamily; requests: number; tokens: number; } /** One completed UTC day of a connected profile: totals only. */ export interface ProfileDayV1 { schemaVersion: typeof PROFILE_SCHEMA_VERSION; day: string; requests: number; tokens: ProfileTokensV1; families: ProfileFamilyRowV1[]; } export interface ProfileCreateV1 { schemaVersion: typeof PROFILE_SCHEMA_VERSION; handle: string; displayName: string; avatar: ProfileAvatar; } /** Public fields of a profile. Never an id, secret, creation day or moderation flag. */ export interface PublicProfileV1 { handle: string; displayName: string; avatar: ProfileAvatar; } export interface ProfilePeriodRankV1 { /** RANK() among non-hidden profiles with a positive metric in the window; null when outside that set. */ rank: number | null; /** Size of the ranked set (0 when nobody is ranked). */ of: number; tokens: number; requests: number; } export interface ProfileRankV1 { profile: PublicProfileV1; metric: ProfileMetric; periods: Record<ProfilePeriod, ProfilePeriodRankV1>; /** Model-family totals over the month window, largest token total first. */ families: ProfileFamilyRowV1[]; } const DAY_MS = 86_400_000; const TOKEN_KEYS = ["input", "cacheRead", "cacheWrite", "output", "reasoning"] as const; const DAY_KEYS = ["schemaVersion", "day", "requests", "tokens", "families"] as const; const FAMILY_KEYS = ["family", "requests", "tokens"] as const; const CREATE_KEYS = ["schemaVersion", "handle", "displayName", "avatar"] as const; const FAMILY_SET: ReadonlySet<string> = new Set(MODEL_FAMILIES); const AVATAR_SET: ReadonlySet<string> = new Set(PROFILE_AVATARS); const RESERVED_SET: ReadonlySet<string> = new Set(PROFILE_RESERVED_HANDLES); /** Letters, combining marks, digits, space and a few punctuation marks; nothing that can form markup or a URL scheme. */ const DISPLAY_NAME_CHARS_RE = /^[\p{L}\p{M}\p{N} ._'-]+$/u; /** Rejects anything shaped like a domain (`example.com`, `x.io`), so a display name cannot be a link. */ const DOMAIN_LIKE_RE = /\.[a-z]{2,}/i; type Result<T> = { ok: true; value: T } | { ok: false; error: string }; function isPlainRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; } function hasExactKeys(record: Record<string, unknown>, expected: readonly string[]): boolean { const keys = Object.keys(record); return keys.length === expected.length && expected.every(key => Object.prototype.hasOwnProperty.call(record, key)); } function isBoundedInt(value: unknown, max: number): value is number { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= max; } export function normalizeProfileHandle(raw: string): string { return raw.trim().toLowerCase(); } export function validateProfileHandle(raw: unknown): Result<string> { if (typeof raw !== "string") return { ok: false, error: "handle must be a string" }; const handle = normalizeProfileHandle(raw); if (handle.length < PROFILE_HANDLE_MIN || handle.length > PROFILE_HANDLE_MAX || !PROFILE_HANDLE_RE.test(handle)) { return { ok: false, error: "handle must be 3-24 lowercase letters, digits or hyphens, starting and ending with a letter or digit" }; } if (handle.includes("--")) return { ok: false, error: "handle must not contain consecutive hyphens" }; if (/^[0-9-]+$/.test(handle)) return { ok: false, error: "handle must contain a letter" }; if (RESERVED_SET.has(handle)) return { ok: false, error: "handle is reserved" }; return { ok: true, value: handle }; } export function validateProfileDisplayName(raw: unknown): Result<string> { if (typeof raw !== "string") return { ok: false, error: "displayName must be a string" }; const name = raw.normalize("NFC").trim(); const length = [...name].length; if (length < 1 || length > PROFILE_DISPLAY_NAME_MAX) { return { ok: false, error: `displayName must be 1-${PROFILE_DISPLAY_NAME_MAX} characters` }; } if (!DISPLAY_NAME_CHARS_RE.test(name)) { return { ok: false, error: "displayName may contain only letters, digits, spaces and . _ ' -" }; } if (name.includes(" ")) return { ok: false, error: "displayName must not contain consecutive spaces" }; if (DOMAIN_LIKE_RE.test(name)) return { ok: false, error: "displayName must not look like a web address" }; return { ok: true, value: name }; } export function isProfileAvatar(value: unknown): value is ProfileAvatar { return typeof value === "string" && AVATAR_SET.has(value); } export function validateProfileCreateV1(input: unknown): Result<ProfileCreateV1> { if (!isPlainRecord(input) || !hasExactKeys(input, CREATE_KEYS)) { return { ok: false, error: "profile must have exactly schemaVersion, handle, displayName and avatar" }; } if (input.schemaVersion !== PROFILE_SCHEMA_VERSION) return { ok: false, error: "unsupported schemaVersion" }; const handle = validateProfileHandle(input.handle); if (!handle.ok) return handle; const displayName = validateProfileDisplayName(input.displayName); if (!displayName.ok) return displayName; if (!isProfileAvatar(input.avatar)) return { ok: false, error: "avatar must be one of the palette colours" }; return { ok: true, value: { schemaVersion: PROFILE_SCHEMA_VERSION, handle: handle.value, displayName: displayName.value, avatar: input.avatar }, }; } export function sumProfileTokens(tokens: ProfileTokensV1): number { return tokens.input + tokens.cacheRead + tokens.cacheWrite + tokens.output + tokens.reasoning; } function parsePeriodRank(value: unknown): ProfilePeriodRankV1 | null { if (!isPlainRecord(value)) return null; const rank = value.rank === null ? null : isBoundedInt(value.rank, Number.MAX_SAFE_INTEGER) && value.rank > 0 ? value.rank : undefined; if (rank === undefined) return null; if (!isBoundedInt(value.of, Number.MAX_SAFE_INTEGER) || !isBoundedInt(value.tokens, Number.MAX_SAFE_INTEGER) || !isBoundedInt(value.requests, Number.MAX_SAFE_INTEGER)) return null; return { rank, of: value.of, tokens: value.tokens, requests: value.requests }; } /** * Parse a rank response from the collector, keeping only the documented fields. Anything that * does not match is rejected rather than rendered. */ export function parseProfileRankV1(value: unknown): ProfileRankV1 | null { if (!isPlainRecord(value) || !isPlainRecord(value.profile) || !isPlainRecord(value.periods)) return null; const handle = validateProfileHandle(value.profile.handle); const displayName = validateProfileDisplayName(value.profile.displayName); if (!handle.ok || !displayName.ok || !isProfileAvatar(value.profile.avatar)) return null; if (value.metric !== "tokens" && value.metric !== "requests") return null; const periods = {} as Record<ProfilePeriod, ProfilePeriodRankV1>; for (const period of PROFILE_PERIODS) { const parsed = parsePeriodRank(value.periods[period]); if (!parsed) return null; periods[period] = parsed; } if (!Array.isArray(value.families)) return null; const families: ProfileFamilyRowV1[] = []; for (const row of value.families) { if (!isPlainRecord(row) || typeof row.family !== "string" || !FAMILY_SET.has(row.family)) return null; if (!isBoundedInt(row.requests, Number.MAX_SAFE_INTEGER) || !isBoundedInt(row.tokens, Number.MAX_SAFE_INTEGER)) return null; families.push({ family: row.family as TelemetryModelFamily, requests: row.requests, tokens: row.tokens }); } return { profile: { handle: handle.value, displayName: displayName.value, avatar: value.profile.avatar }, metric: value.metric, periods, families, }; } function utcMidnight(epochMs: number): number { const d = new Date(epochMs); return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()); } /** * True for a completed UTC day no older than {@link PROFILE_SUBMIT_MAX_AGE_DAYS}. Today and the * future are never submittable: only whole, finished days are ranked. */ export function isSubmittableProfileDay(day: string, now: number): boolean { const dayMs = parseCalendarUtcDayMs(day); if (dayMs === null) return false; const todayMs = utcMidnight(now); return dayMs < todayMs && dayMs >= todayMs - PROFILE_SUBMIT_MAX_AGE_DAYS * DAY_MS; } export function validateProfileDayV1(input: unknown, now: number = Date.now()): Result<ProfileDayV1> { if (!isPlainRecord(input) || !hasExactKeys(input, DAY_KEYS)) { return { ok: false, error: "day must have exactly schemaVersion, day, requests, tokens and families" }; } if (input.schemaVersion !== PROFILE_SCHEMA_VERSION) return { ok: false, error: "unsupported schemaVersion" }; if (typeof input.day !== "string" || !isSubmittableProfileDay(input.day, now)) { return { ok: false, error: `day must be a completed UTC day within the last ${PROFILE_SUBMIT_MAX_AGE_DAYS} days` }; } if (!isBoundedInt(input.requests, PROFILE_MAX_DAY_REQUESTS) || input.requests === 0) { return { ok: false, error: `requests must be an integer in 1..${PROFILE_MAX_DAY_REQUESTS}` }; } const rawTokens = input.tokens; if (!isPlainRecord(rawTokens) || !hasExactKeys(rawTokens, TOKEN_KEYS)) { return { ok: false, error: "tokens must have exactly input, cacheRead, cacheWrite, output and reasoning" }; } for (const key of TOKEN_KEYS) { if (!isBoundedInt(rawTokens[key], PROFILE_MAX_DAY_TOKENS)) return { ok: false, error: `tokens.${key} is out of range` }; } const tokens: ProfileTokensV1 = { input: rawTokens.input as number, cacheRead: rawTokens.cacheRead as number, cacheWrite: rawTokens.cacheWrite as number, output: rawTokens.output as number, reasoning: rawTokens.reasoning as number, }; const tokenSum = sumProfileTokens(tokens); if (tokenSum > PROFILE_MAX_DAY_TOKENS) return { ok: false, error: "token total exceeds the daily limit" }; if (!Array.isArray(input.families) || input.families.length === 0 || input.families.length > MODEL_FAMILIES.length) { return { ok: false, error: "families must list 1 or more model families" }; } const seen = new Set<string>(); const families: ProfileFamilyRowV1[] = []; let familyRequests = 0; let familyTokens = 0; for (const row of input.families) { if (!isPlainRecord(row) || !hasExactKeys(row, FAMILY_KEYS)) { return { ok: false, error: "family rows must have exactly family, requests and tokens" }; } if (typeof row.family !== "string" || !FAMILY_SET.has(row.family)) return { ok: false, error: "unknown model family" }; if (seen.has(row.family)) return { ok: false, error: "duplicate model family" }; seen.add(row.family); if (!isBoundedInt(row.requests, PROFILE_MAX_DAY_REQUESTS) || row.requests === 0) { return { ok: false, error: "family requests must be positive" }; } if (!isBoundedInt(row.tokens, PROFILE_MAX_DAY_TOKENS)) return { ok: false, error: "family tokens are out of range" }; familyRequests += row.requests; familyTokens += row.tokens; families.push({ family: row.family as TelemetryModelFamily, requests: row.requests, tokens: row.tokens }); } if (familyRequests !== input.requests) return { ok: false, error: "family requests must sum to requests" }; if (familyTokens !== tokenSum) return { ok: false, error: "family tokens must sum to the token total" }; return { ok: true, value: { schemaVersion: PROFILE_SCHEMA_VERSION, day: input.day, requests: input.requests, tokens, families } }; }