Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 5 additions & 8 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,11 @@ BACKEND_URL=localhost:3000
# INFLUXDB_TOKEN=your influxdb token goes here
# INFLUXDB_URL=http://localhost:8086

# Phase 4b: set all four required values to authenticate the bot. With all absent,
# requests stay anonymous. Partial configuration is a startup error.
# IDP_PUBLIC_URL=https://auth.polinetwork.org
# PoliNetwork IdP (required): the bot calls the backend only with its service token.
IDP_PUBLIC_URL=https://auth.polinetwork.org
# Optional transport URL inside the cluster; issuer/audience still use the public URL.
# IDP_INTERNAL_URL=http://auth:3000
# OAUTH_BACKEND_RESOURCE_URI=https://backend.internal.polinetwork.org
# OAUTH_BOT_CLIENT_ID=<registered telegram-bot client ID>
OAUTH_BACKEND_RESOURCE_URI=https://backend.internal.polinetwork.org
OAUTH_BOT_CLIENT_ID=#registered telegram-bot client ID
# Private JWK JSON, with kid/alg/d; inject from the bot's Key Vault secret.
# OAUTH_BOT_PRIVATE_JWK=<private JWK JSON>
# Defaults to shadow: keep legacy decisions and log IdP differences.
IDP_DECISIONS=shadow
OAUTH_BOT_PRIVATE_JWK=#private JWK JSON
54 changes: 21 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ first-post classifications with reasons and cross-chat counts, join decisions an
review delivery, local bans, network BanAll starts, moderator decisions, and dependency failures. Identifiers let
operators correlate actions without logging raw message text, contact details, or the fingerprint secret.

## IdP migration (Phase 4b)
## IdP authorization

The bot uses `@polinetwork/auth-kit` to obtain a cached `client_credentials` token with
`private_key_jwt`. Register a separate `telegram-bot` client in the IdP and link it to the backend
Expand All @@ -90,11 +90,11 @@ resource. Its scopes are `backend:tg:read`, `backend:tg:ingest`, `backend:tg:gro
inject the private JWK from the bot's Key Vault as `OAUTH_BOT_PRIVATE_JWK` (JSON with `kid`, `alg`
and private key material). Never put the key in the repository or logs.

Set `IDP_PUBLIC_URL`, `OAUTH_BACKEND_RESOURCE_URI`, `OAUTH_BOT_CLIENT_ID` and
`OAUTH_BOT_PRIVATE_JWK` together. `IDP_INTERNAL_URL` optionally routes token requests inside the
cluster; assertion audiences retain the public token URL. An entirely absent configuration
keeps anonymous calls. A partial configuration fails startup. `BACKEND_URL` continues to be a
host and port, without a URL scheme, matching the existing backend transport.
`IDP_PUBLIC_URL`, `OAUTH_BACKEND_RESOURCE_URI`, `OAUTH_BOT_CLIENT_ID` and
`OAUTH_BOT_PRIVATE_JWK` are required; startup fails without them. The bot never calls the backend
anonymously. `IDP_INTERNAL_URL` optionally routes token requests inside the cluster; assertion
audiences retain the public token URL. `BACKEND_URL` continues to be a host and port, without a URL
scheme, matching the existing backend transport.

Each human update gets an isolated actor client (`ctx.backend`, `X-PN-Actor: telegram:<id>`).
Service-only operations, including buffered message/user ingestion, group synchronization,
Expand All @@ -105,48 +105,36 @@ persist a tRPC client. A batch belongs to one client and cannot mix actors. Back
fall back to anonymous transport. The socket authenticates with `auth.token`; a server expiry
disconnect triggers reconnect, and rejected handshakes invalidate the token with retry backoff.

`IDP_DECISIONS=shadow` is the default. It computes both checks, logs `[ACCESS] shadow` differences,
and acts exclusively on the original role decision. Legacy roles and group administrators are
read anonymously; grant interruption also stays on the anonymous legacy path with
`interruptedById`. `/audit` uses the service read path during shadow, so the backend's actor
permission check cannot override the legacy command decision. The backend must keep
`LEGACY_ANONYMOUS=allow` throughout shadow. Grants are read through the backend's migration
helper, which includes active grants from both tables. An IdP lookup failure is logged and never
changes a successful shadow decision.

After comparing differences for roughly a week and reconciling roles and Telegram links, set
`IDP_DECISIONS=enforce` to apply IdP permissions. An unavailable actor check denies actions;
native chat administrators retain the documented chat-local shortcut. Immunity applies to every
Commands, callback menus and target checks act on the IdP permissions resolved through
`tg.access.resolve` (RFC v3 §10.2). An unavailable actor check denies actions; native chat
administrators (Telegram status `administrator` or `creator`) retain the documented chat-local
shortcut, which replaces the removed `tg_group_admins` table. Immunity (`tg:immune`) applies to every
ban-all entry point at enqueue; jobs already accepted continue without permission rechecks.
`/getroles` lists the legacy roles until enforcement, then the IdP permissions. `/addrole`,
`/delrole`, `/link` and the unregistered test commands remain in this transitional source tree;
remove them and the legacy role/group-admin checks in the coordinated cleanup before setting
`LEGACY_ANONYMOUS=deny`.
Switching the mode alone does not remove those legacy commands.
`/getroles` lists the IdP permissions. Roles are managed in the IdP, so the bot no longer has
`/addrole`, `/delrole` or `/link`.

Moderation audit records use `tg.auditLog.record` and a Redis outbox with stable idempotency keys,
actor IDs and the basis (`idp_permission`, `telegram_chat_admin`, `automatic`, `telegram_ui`).
Automatic actions have no human actor. During shadow, a legacy role pass uses the permission
path basis; the backend flags cases where the snapshot does not back that claim for review.
Automatic actions have no human actor; the backend flags `idp_permission` records that the
snapshot does not back for review.
Redis hashes and a due-time sorted set are changed atomically. Backend outages retry with capped
exponential backoff; permanent input errors move to `audit-outbox:dead` for inspection. Enable
Redis AOF, use persistent storage and a non-evicting policy for the audit data. Shutdown keeps
Redis alive until the runner, buffered storage and module workers stop. If Redis cannot store a
record, the bot attempts direct delivery; if both systems fail the full record is logged as lost.
This fallback is best effort: durability requires functioning persistent Redis, and a crash
between a Telegram action and its outbox write can still lose that action's audit record. Ban-all
token-authenticated flow creation persists audit recovery data atomically with the job. Audit delivery starts only
flow creation persists audit recovery data atomically with the job. Audit delivery starts only
after a confirmed insertion; caller retries and the resumed orchestrator deliver the same key,
so a crash in between is recovered without duplicate history. Older jobs without this recovery
data keep their original behavior. Anonymous flows record once and do not replay because the
legacy audit endpoint has no idempotency support.
data keep their original behavior.

Grant socket messages accept both the legacy `adminId` and the new `{ sub, telegramId,
displayName }` actor. A dashboard user without a linked Telegram account can therefore be shown
by display name in the grants topic.

Deploy the Phase 3 backend API/SDK before enabling these variables. Validate token acquisition,
service-only ingestion, actor isolation, socket expiry/reconnect, audit retry/deduplication and
shadow differences in a test environment. Unit tests do not verify real IdP, Telegram or Key
Vault connectivity. Roll back the bot image/configuration while keeping backend anonymous
compatibility enabled; keep Redis persistence so pending audits survive a rollback/restart.
Validate token acquisition, service-only ingestion, actor isolation, socket expiry/reconnect and
audit retry/deduplication in a test environment. Unit tests do not verify real IdP, Telegram or Key
Vault connectivity. Keep Redis persistence so pending audits survive a rollback/restart. Bot images
from before this cleanup still call the backend anonymously; rolling back to one needs the
backend's `LEGACY_ANONYMOUS=allow`.
6 changes: 6 additions & 0 deletions docs/idp-phase4b-handoff.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Phase 4b Telegram handoff

> **Superseded by the Phase 5 bot cleanup.** Cutover step 7 is done: `/addrole`, `/delrole`,
> `/link`, `/test_db`, the shadow mode and every anonymous backend call are removed, so
> `IDP_DECISIONS` no longer exists and the IdP variables are required. The bot always applies IdP
> decisions; native chat admins replace `tg_group_admins`. This document is kept as the
> record of Phase 4b; see the README for the current behaviour.

Branch: `feat/idp-phase4b-bot`. The working tree contains the completed local implementation;
no commit, staging, push, PR or deployment was performed during continuation.

Expand Down
52 changes: 0 additions & 52 deletions src/access/decision.ts
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
import type { Logger } from "pino"
import { PERMISSION, type Permission } from "./catalog"

/**
* - `anonymous`: the IdP is not configured; only the legacy role checks exist.
* - `shadow`: both checks run, the legacy one is applied and differences are logged (RFC v3 §13).
* - `enforce`: the IdP decision is applied.
*/
export type DecisionMode = "anonymous" | "shadow" | "enforce"

/** A Telegram user as `tg.access.resolve` describes them. */
export type AccessEntry = {
sub: string | null
Expand Down Expand Up @@ -55,47 +47,3 @@ export async function idpDecision(options: {
if (failure) throw failure.error
return DENIED
}

export type DecideOptions<T> = {
mode: DecisionMode
/** Names the check in logs, e.g. `command:/ban`. */
check: string
/** Telegram IDs that identify the case in logs. Nothing else about the people is logged. */
ids: Record<string, number | undefined>
legacy: () => Promise<T>
idp: () => Promise<T>
/** Whether two outcomes are the same decision. Default: `Object.is`. */
same?: (legacy: T, idp: T) => boolean
logger: Pick<Logger, "warn">
}

export const sameAllowed = (a: Decision, b: Decision) => a.allowed === b.allowed

/**
* Runs the check the mode calls for. In shadow mode both run, the legacy outcome is returned (or
* its error thrown) and any difference is logged; the IdP outcome is never acted on, and never
* combined with the legacy one.
*/
export async function decide<T>(options: DecideOptions<T>): Promise<T> {
if (options.mode === "anonymous") return options.legacy()
if (options.mode === "enforce") return options.idp()

const [legacy, idp] = await Promise.allSettled([options.legacy(), options.idp()])
const context = { check: options.check, ...options.ids }
const legacyOutcome = legacy.status === "fulfilled" ? legacy.value : "error"
if (idp.status === "rejected") {
options.logger.warn(
{ ...context, legacy: legacyOutcome, idpError: errorMessage(idp.reason) },
"[ACCESS] shadow: IdP decision unavailable"
)
} else if (legacy.status === "rejected" || !(options.same ?? Object.is)(legacy.value, idp.value)) {
options.logger.warn({ ...context, legacy: legacyOutcome, idp: idp.value }, "[ACCESS] shadow: decisions differ")
}

if (legacy.status === "rejected") throw legacy.reason
return legacy.value
}

function errorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error)
}
60 changes: 10 additions & 50 deletions src/access/index.ts
Original file line number Diff line number Diff line change
@@ -1,29 +1,11 @@
import { type Backend, idpConfig, legacyBackend } from "@/backend"
import { env } from "@/env"
import type { Backend } from "@/backend"
import { logger } from "@/logger"
import type { Role } from "@/utils/types"
import type { Permission } from "./catalog"
import {
type AccessEntry,
DENIED,
type DecideOptions,
type Decision,
type DecisionMode,
decide,
idpDecision,
NO_ACCESS,
sameAllowed,
} from "./decision"
import { type AccessEntry, DENIED, type Decision, idpDecision, NO_ACCESS } from "./decision"

export { PERMISSION, type Permission } from "./catalog"
export * from "./decision"

if (!idpConfig && env.IDP_DECISIONS === "enforce")
throw new Error("IDP_DECISIONS=enforce needs the IdP configuration (IDP_PUBLIC_URL, OAUTH_BOT_*)")

/** How the bot decides who may do what (RFC v3 §13 Phase 4). */
export const decisionMode: DecisionMode = idpConfig ? env.IDP_DECISIONS : "anonymous"

/** IdP access of Telegram users, from the backend's snapshot. Unlinked users hold nothing. */
export async function resolveAccess(backend: Backend, telegramIds: number[]): Promise<Map<number, AccessEntry>> {
const resolved = await backend.tg.access.resolve.query({ telegramIds })
Expand All @@ -39,14 +21,9 @@ export async function resolveOne(backend: Backend, telegramId: number): Promise<
return (await resolveAccess(backend, [telegramId])).get(telegramId) ?? NO_ACCESS
}

/** {@link decide} in the configured mode. */
export function decideAccess<T>(options: Omit<DecideOptions<T>, "mode" | "logger">): Promise<T> {
return decide({ ...options, mode: decisionMode, logger })
}

/**
* Whether a person may run a command or press a button (RFC v3 §10.2), in the configured mode.
* Once IdP decisions apply, an unavailable decision denies; legacy failures surface as before.
* Whether a person may run a command or press a button (RFC v3 §10.2). An unavailable decision
* denies.
*/
export async function authorizeAction(options: {
check: string
Expand All @@ -57,31 +34,14 @@ export async function authorizeAction(options: {
required: readonly Permission[]
/** Set only where the chat's native admins may act too (RFC v3 §4 decision 2). */
isChatAdmin?: () => Promise<boolean>
legacy: () => Promise<Decision>
}): Promise<Decision> {
return decideAccess({
check: options.check,
ids: { actorId: options.actorId, chatId: options.chatId },
legacy: options.legacy,
idp: () =>
idpDecision({
required: options.required,
actor: () => resolveOne(options.backend, options.actorId),
isChatAdmin: options.isChatAdmin,
}),
same: sameAllowed,
return idpDecision({
required: options.required,
actor: () => resolveOne(options.backend, options.actorId),
isChatAdmin: options.isChatAdmin,
}).catch((error: unknown) => {
if (decisionMode !== "enforce") throw error
logger.error({ error, check: options.check, actorId: options.actorId }, "[ACCESS] IdP decision unavailable, denied")
const { check, actorId, chatId } = options
logger.error({ error, check, actorId, chatId }, "[ACCESS] IdP decision unavailable, denied")
return DENIED
})
}

/**
* Roles from the legacy `tg_permissions` table. Used only by the legacy side of a decision and the
* legacy role commands; goes away with the switch to IdP decisions.
*/
export async function legacyRoles(userId: number): Promise<Role[]> {
const { roles } = await legacyBackend.tg.permissions.getRoles.query({ userId })
return roles ?? []
}
35 changes: 11 additions & 24 deletions src/backend.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,63 +17,50 @@ export type Backend = TRPCClient<AppRouter>
export type ApiOutput = inferRouterOutputs<AppRouter>
export type ApiInput = inferRouterInputs<AppRouter>

/** The bot's IdP client configuration; null while it still calls the backend anonymously. */
export const idpConfig = parseIdpConfig(env)

/** The `telegram-bot` service token (RFC v3 §10.1), cached and renewed at half its lifetime. */
export const serviceTokens: TokenSource | null = idpConfig
? serviceTokenSource({
...idpConfig,
onError: (error) => logger.warn({ error }, "[IDP] service token renewal failed, using the cached token"),
})
: null
export const serviceTokens: TokenSource = serviceTokenSource({
...parseIdpConfig(env),
onError: (error) => logger.warn({ error }, "[IDP] service token renewal failed, using the cached token"),
})

function createBackendClient(tokens: TokenSource | null, actorTelegramId: number | null = null): Backend {
function createBackendClient(tokens: TokenSource, actorTelegramId: number | null = null): Backend {
return createTRPCClient<AppRouter>({
links: [
trpcTelemetryLink,
httpBatchLink({
url,
transformer: SuperJSON,
fetch: tokens ? authenticatedFetch(tokens, actorTelegramId) : undefined,
fetch: authenticatedFetch(tokens, actorTelegramId),
}),
],
})
}

/**
* Acts as the bot itself: background work (storage flush, ban-all, cron, startup) and every lookup
* the backend grants only to the service (RFC v3 §8.1). Anonymous when the IdP is not configured.
* the backend grants only to the service (RFC v3 §8.1).
*/
export const serviceBackend: Backend = createBackendClient(serviceTokens)

/**
* Always anonymous. Only for the procedures the RFC removes and the backend refuses to token
* callers (`tg.permissions.*`, `tg.link.link`, `tg.auditLog.create`, `test.dbQuery`), which keep
* working while the backend allows legacy calls (RFC v3 §13).
*/
export const legacyBackend: Backend = serviceTokens ? createBackendClient(null) : serviceBackend

/**
* Acts for a Telegram user through `X-PN-Actor` (RFC v3 §6.3). The backend accepts such an actor
* only on `tg.access.resolve`, `tg.grants.interrupt` and `tg.auditLog.getById`, and checks the
* person's IdP permissions there.
*/
export function backendAs(telegramId: number): Backend {
return serviceTokens ? createBackendClient(serviceTokens, telegramId) : serviceBackend
return createBackendClient(serviceTokens, telegramId)
}

/** One client per update: acting for its human sender, otherwise the service (RFC v3 §10.1). */
export function backendFor(from: User | undefined): Backend {
return from && !from.is_bot ? backendAs(from.id) : serviceBackend
}

/** Startup check; with a token it also proves the IdP issues one the backend accepts. */
/** Startup check; it also proves the IdP issues a token the backend accepts. */
export async function backendHealthCheck(botId: number) {
try {
if (serviceTokens) await serviceBackend.tg.access.resolve.query({ telegramIds: [botId] })
else await legacyBackend.test.dbQuery.query({ dbName: "tg" })
logger.info(`[BACKEND] connected${serviceTokens ? " with the IdP service token" : ""}`)
await serviceBackend.tg.access.resolve.query({ telegramIds: [botId] })
logger.info("[BACKEND] connected with the IdP service token")
} catch (err) {
if (err instanceof TRPCClientError && err.message.startsWith("fetch failed"))
logger.error(`[BACKEND] can't connect`)
Expand Down
Loading
Loading