Design Telegram human-in-the-loop capability approvals

[ak5]

Goal

Add an optional human-in-the-loop approval flow in which an external Telegram
bot presents a precise requested capability and an authorized person may deny
it or approve it once or through a bounded reusable rule.

Example prompt:

Is workload release-agent in workspace ws-123 allowed to run
gh issue close 456 against github.com/acme/widgets?

Actions:

• Deny
• Allow once
• Allow for this session
• Always allow this exact operation
• Always allow this bounded operation class (for example, GitHub Issues
  operations for one tenant/persona/repository)

Architectural constraint

Telegram is an approval user interface, not part of Charon's credential data
plane and not a source of credential, endpoint, provider, item, hostname,
method, path, or secret-reference selection.

An external approval broker should:

1. receive a normalized capability request from the integrating control plane;
2. render only redacted identity and concrete operation information;
3. authenticate an allowlisted Telegram chat/user;
4. record the decision and any bounded reusable rule;
5. return a signed approval assertion to the workload-identity issuer; and
6. let the issuer mint Charon's existing short-lived, single-use manifest.

Charon should continue verifying manifests offline. It must not call Telegram or
wait on a chat interaction while holding an HTTP request or resolved secret.

Required decisions

• Define the normalized approval-request schema and canonical request digest.
• Decide whether approval assertions need their own key and schema or remain an
  issuer-internal contract.
• Define the exact predicates available to reusable rules:
  • tenant, persona, workload, and optionally workspace;
  • service and exact account/organization/repository resource;
  • named capability and operation class;
  • maximum duration, use count, and manifest TTL;
  • environment or risk tier.
• Define an approval session as an issuer-authenticated tenant, persona,
  workspace, and active lease tuple—not a Telegram chat session or a
  workload-supplied identifier.
• Bound session approval by the earliest of lease termination, workspace
  disposal, explicit revocation, inactivity timeout, and configured maximum
  duration.
• Define which operations can never receive reusable approval.
• Define rule creation, listing, expiry, revocation, and emergency disable.
• Define behavior when Telegram or the approval broker is unavailable
  (fail closed).
• Decide how Telegram account recovery, bot-token rotation, and chat migration
  affect authorization.

“Always” must never mean an unbounded natural-language match. A label such as
“anything relating to GitHub Issues” must compile to inspectable structured
predicates, such as one persona, one repository, a fixed set of issue
operations, and a bounded expiry.

Security requirements

• Bind each prompt and callback to a random, single-use, expiring approval ID
  and a digest of the complete normalized request.
• Reject stale, replayed, edited, duplicated, or mismatched callbacks.
• Use Telegram numeric user and chat IDs from an operator allowlist; do not
  authorize by username or display name.
• Ensure only the current pending message can mutate its decision; edit it to a
  terminal redacted result after use.
• Keep bot tokens, approval-signing keys, manifests, nonces, credentials,
  provider references, and private resource data out of messages and logs.
• Make deny and timeout the default.
• Never let session approval survive lease replacement, workspace resume into a
  new lease, persona reassignment, or approval-broker restart without durable,
  revocable state.
• Mint a fresh short-lived, single-use Charon manifest for every operation
  covered by a session approval; the approval itself is never a reusable
  Charon bearer token.
• Require stronger confirmation for creating or widening reusable rules.
• Prevent a workload from selecting or weakening the reusable-rule scope.
• Preserve Charon's independent concrete destination/method/path enforcement;
  human approval cannot override local deny-by-default policy.
• Emit correlated, redacted audit records for request, delivery, decision,
  rule match, issuer result, revocation, and timeout.
• Rate-limit prompts and prevent approval-notification flooding.
• Document Telegram as an external availability and account-takeover risk, not
  as a secret store.

Suggested contracts

• approval-request.schema.json
• approval-decision.schema.json
• approval-rule.schema.json
• Optional OpenAPI for the approval broker's authenticated control-plane API
• Telegram adapter behind an ApprovalChannel interface so other channels can
  be added without changing decision semantics

The channel adapter should only deliver a presentation model and return an
opaque decision callback. Policy normalization and authorization belong in the
approval broker, not Telegram-specific code.

Acceptance criteria

• ADR records trust boundaries, rule semantics, failure behavior, and
  rejected alternatives.
• Telegram bot supports deny, allow-once, session-duration approval, exact
  reusable approval, and bounded operation-class approval.
• Allow-once cannot be replayed and expires before or with the resulting
  manifest.
• Session approval is bound to one authenticated tenant/persona/workspace/
  lease tuple and ends on lease termination, disposal, revocation,
  inactivity timeout, or maximum duration.
• Suspend/resume or lease replacement does not carry session approval into
  the new lease.
• Reusable rules are structured, inspectable, expiring, and revocable.
• Cross-tenant, cross-persona, cross-workspace, cross-repository, widened
  operation, edited callback, duplicate callback, and expired callback
  attempts fail.
• Telegram outage, bot removal, unknown user/chat, and approval-broker
  outage fail closed without interrupting already authorized unrelated
  realms.
• Charon has no Telegram dependency and makes no online approval lookup.
• No prompt, callback, API response, log, trace, or fixture leaks
  credentials, manifests, nonces, signing keys, provider references, or
  private keys.
• Threat model, integration-boundary documentation, and operator runbook
  are updated.

[ak5]

Contract-first foundation merged to dev in #13.

Completed design slice:

• ADR 0005 trust boundaries, grant semantics, non-reusable operations, outage behavior, keys, and rejected alternatives
• closed request, decision, reusable-rule, and signed-assertion JSON Schemas
• RFC 8785 + SHA-256 canonical digest contract with regression vector
• mutually authenticated approval-broker OpenAPI
• channel-neutral ApprovalChannel contract for Telegram and future adapters
• operator runbook for provisioning, rotation, recovery, revocation, and emergency disable
• threat-model and integration-boundary updates

Charon runtime remains independent of Telegram and the broker. The issue stays open for broker storage/policy implementation, issuer assertion verification, Telegram adapter, and adversarial end-to-end tests.

[renezander030]

The required decisions cover granting and revoking a bounded rule, but revocation only points forward. When one use of an always-allow class turns out to be wrong, you need to enumerate the other operations that rule authorized under the same assumptions, and nothing links a minted manifest back to the approval that produced it. Does the issuer persist that link, or does the audit path stop at the signed assertion?

Same shape we ended up with for the approval record: https://gist.github.com/renezander030/ad81c7a805a09a844983f881e2c487e5