approval-md 0.2.0 → 0.4.0

package/dist/src/channels/telegram.d.ts

@@ -34,22 +34,59 @@
  * notify, long-poll, callbacks, failure modes — against a local mock Bot API
  * server and never touches the real network.
  *
+ * ## Two transports, one update path (APRV-424)
+ *
+ * An update reaches this channel either because it long-polled for it
+ * ({@link TelegramChannel.pollOnce}) or because Telegram posted it to a URL the
+ * runtime registered ({@link TelegramChannel.deliverUpdate}, fed by
+ * `channels/telegram-webhook.ts`). That is the WHOLE of the difference. Both
+ * entry points hand the update to the same {@link TelegramChannel.handleUpdate}
+ * and therefore to the same chat check, the same `senderOf`, the same
+ * resolution ladder, the same `onDecision` handler and the same
+ * annotate-after-decision edit; a decision does not know which door it came
+ * through, and there is no second copy of any of it to drift.
+ *
+ * The two are mutually exclusive per bot, and the Bot API says so first:
+ * `getUpdates` is refused outright while a webhook is set.
+ * {@link TelegramChannel.claimTransport} refuses the in-process form of the
+ * mistake, and the verbs above ask `getWebhookInfo` and the ownership registry
+ * about the cross-process one.
+ *
  * ## Config-declared identity — SPEC.md §11
  *
  * > Human identity in v0.1 is config-declared (an environment variable or
  * > flag); the trust boundary is the local machine, and anyone who can set that
  * > configuration and write to the log is inside it.
  *
- * This channel does **not** authenticate the person who tapped the button. It
- * checks that the callback arrived from the configured chat id, and the
- * decision is then recorded against the human actor the *runtime* was
- * configured with (`APPROVAL_HUMAN` / `--as`), not against anything the
- * callback carried. So the guarantee is "someone with access to the configured
- * chat, on a runtime configured by someone with local control, tapped Approve"
- * — not "alice tapped Approve". Anyone in that chat can approve as the
- * configured actor. Use a private chat with the bot, and treat the chat's
- * membership as part of the trust boundary. Cryptographic identity is future
- * work and is not a v0.1 claim.
+ * What this channel authenticates, exactly: that the callback arrived **from
+ * the configured chat id**, and which **Telegram account** the Bot API
+ * attributes the tap to (`callback_query.from.id`). It authenticates no
+ * person, because no transport can: an account id is evidence about an
+ * account.
+ *
+ * What is done with the second fact is the operator's to decide, and since
+ * APRV-324 there are two settings:
+ *
+ * - **No `senders` block in the policy.** Nothing changes from every build
+ *   before it. The decision is recorded against the human actor the *runtime*
+ *   was configured with (`APPROVAL_HUMAN` / `--as`), so the guarantee is
+ *   "someone with access to the configured chat, on a runtime configured by
+ *   someone with local control, tapped Approve" — not "alice tapped Approve".
+ *   Anyone in that chat can approve as the configured actor. Use a private chat
+ *   with the bot, and treat the chat's membership as part of the trust
+ *   boundary.
+ * - **A `senders` block mapping account ids to approvers.** The decision is
+ *   recorded against the person the operator attested that account to, and a
+ *   tap from an account the policy does not name is REFUSED rather than
+ *   recorded under the listener's identity. The guarantee becomes "the account
+ *   the operator attested to alice tapped Approve", which is a statement about
+ *   Telegram's session handling and the operator's assertion, and still not a
+ *   proof of personhood. Cryptographic identity is future work and is not a
+ *   v0.1 claim.
+ *
+ * The channel itself resolves nothing either way. It reports the account it
+ * saw; `channels/contract.ts` resolves it against the attested policy, and
+ * `core/gate.ts` decides. See `design/channel-sender-identity.md`.
  *
  * ## Formatting: HTML, not MarkdownV2 — a deliberate choice
  *
@@ -183,6 +220,7 @@
  * and the log is not opened.
  */
 import type { ChannelBatch, ChannelDecision, ChannelHealth, ChannelRequest, DecisionOutcome, DeliveryId, RenderedRequest, TaggedField, TestableChannel } from "./contract.js";
+import type { ChannelSender } from "../core/sender-identity.js";
 import { type Reaction, type ReviewVerdict } from "../core/audit.js";
 import { type PromptLayout } from "../core/prompt-layout.js";
 export { TELEGRAM_CHAT_ENV, TELEGRAM_TOKEN_ENV, telegramChatEnvFor, telegramTokenEnvFor, } from "../core/telegram-config.js";
@@ -341,6 +379,13 @@ export declare function decidedLine(actor: string, ts: string, seq: number): str
 export declare const TELEGRAM_DEFAULT_RETENTION_MS: number;
 /** Least time between two sweeps. A sweep is O(map); once a minute is plenty. */
 export declare const TELEGRAM_SWEEP_INTERVAL_MS = 60000;
+/**
+ * How many refused cards' nonces a channel remembers as dead (APRV-442).
+ *
+ * A bound on memory and nothing else: a nonce that falls off the end reaches
+ * the action-reference fallback, and the gate judges that tap in full.
+ */
+export declare const TELEGRAM_REFUSED_NONCE_CAP = 1024;
 /**
  * The slice of `fetch` this module uses, structurally.
  *
@@ -556,6 +601,13 @@ export type CheckpointTapHandler = (tap: {
         seq: number;
         hash: string;
     };
+    /**
+     * The account the transport authenticated (APRV-324 follow-up), when it
+     * authenticated one. The channel resolves nothing: the runtime's handler
+     * asks the attested policy who this is, refuses an account it does not name,
+     * and signs as the person it does.
+     */
+    sender?: ChannelSender;
 }) => CheckpointTapResponse | Promise<CheckpointTapResponse>;
 export declare const TELEGRAM_COMMANDS: readonly ["queue", "skip", "next"];
 export type TelegramCommand = (typeof TELEGRAM_COMMANDS)[number];
@@ -804,6 +856,14 @@ export interface DigestState {
      * the request's own `ts` remains the only instant a TTL is measured from.
      */
     deliveredAtMs: number;
+    /**
+     * How long after {@link deliveredAtMs} the LAST of this digest's members can
+     * still be decided, or `null` when some member is bounded by nothing
+     * (APRV-423, second review pass). The widest of the members' own windows
+     * ({@link Delivery.windowMs}), because a digest is droppable only once every
+     * member is past deciding.
+     */
+    windowMs: number | null;
 }
 /**
  * The computed facts a digest's members share, as the digest states them.
@@ -904,6 +964,30 @@ export declare function parseCheckpointCallback(data: unknown): {
     sign: boolean;
     nonce: string;
 } | null;
+/**
+ * The account the Bot API attributes a callback to (APRV-324, amended SPEC.md
+ * §10.3).
+ *
+ * `callback_query.from.id` and nothing else. Telegram assembles the `from`
+ * object itself, from the session the tap arrived on, which is why it is the
+ * one field on an update this channel treats as evidence about a person. Three
+ * neighbours are deliberately not read:
+ *
+ * - **`from.username`.** Mutable and reusable, so a mapping keyed on it would
+ *   hand an identity over with a handle. Never a key here and never recorded
+ *   (`core/sender-identity.ts` states the argument in full).
+ * - **`message.from`.** The author of the message the button sits on — this bot
+ *   — rather than the person who pressed it.
+ * - **`data`, and any text.** What the sender says about themselves, which
+ *   §11.1 invariant 4 says may raise scrutiny and never lower it. A callback
+ *   whose payload names a user id names it about itself; the id here comes from
+ *   the transport, and the two disagreeing changes nothing.
+ *
+ * `undefined` when the update carries no usable id: a sender this channel could
+ * not read is not a sender it may guess at, and the decision then travels with
+ * none, which the contract reads as today's configured attribution.
+ */
+export declare function senderOf(query: Record<string, unknown>, channel: string): ChannelSender | undefined;
 interface ParsedCallback {
     decision: "grant" | "reject";
     /** `all` for a digest's "all" button; `one` for every per-request button. */
@@ -978,6 +1062,18 @@ export interface ReviewTap {
     reaction?: Reaction;
     /** The human's words, when a note prompt collected any. */
     note?: string;
+    /**
+     * The account the transport authenticated (APRV-324 follow-up), when it
+     * authenticated one.
+     *
+     * A review confers no authority, which is why it took the paragraph above so
+     * long to stop being true. It is still recorded as a HUMAN's observation and
+     * `approval feedback` presents it to agents as human-authored guidance, so a
+     * review attributed to the wrong person is guidance in somebody else's name.
+     * The channel resolves nothing; the runtime's handler asks the attested
+     * policy, refuses an account it does not name, and records the one it does.
+     */
+    sender?: ChannelSender;
 }
 /** What the runtime did with a review tap, as it reports it back. */
 export interface ReviewTapResponse {
@@ -1051,11 +1147,20 @@ export interface ReviewCardState {
         headline: string;
         lines: string[];
     } | null;
-    /** The outstanding note prompt, and what its reply will record. */
+    /**
+     * The outstanding note prompt, and what its reply will record.
+     *
+     * `sender` is the account that asked for the prompt (APRV-324 follow-up),
+     * when the transport authenticated one. A ForceReply prompt is addressed to
+     * the person who tapped, and the words it collects are recorded as theirs, so
+     * a reply from a different account is not the answer to this question: it is
+     * left unrecorded and the prompt stays live for whoever armed it.
+     */
     awaitingNote: {
         promptId: DeliveryId;
         verdict: ReviewVerdict;
         reaction: Reaction;
+        sender?: ChannelSender;
     } | null;
     /** When this process delivered the card, on {@link TelegramConfig.now}'s clock. */
     deliveredAtMs: number;
@@ -1161,6 +1266,17 @@ export declare class TelegramApiError extends Error {
  * that goes unreported.
  */
 export declare function isMessageNotModified(cause: unknown): boolean;
+/**
+ * Whether a failed poll is the Bot API saying another process holds this bot
+ * (APRV-390).
+ *
+ * It is the one poll failure that is not transient and not the network's
+ * fault: retrying it forever produces an identical line every few seconds and
+ * never recovers, because the other poller is not going to stop. {@link
+ * TelegramChannel.listen} reports it once, with whatever the caller knows
+ * about who the other process is, and then stops repeating itself.
+ */
+export declare function isPollConflict(cause: unknown): boolean;
 /** What one `pollOnce()` did, for tests and for programmatic drivers. */
 export interface TelegramPollResult {
     /** Updates received in this batch. */
@@ -1187,6 +1303,50 @@ export interface TelegramPollResult {
         ok: boolean;
     }[];
 }
+/**
+ * How updates reach this channel (APRV-424).
+ *
+ * `poll` is `getUpdates`, the transport every build before APRV-424 had.
+ * `webhook` is Telegram posting each update to a URL the runtime registered.
+ * They are alternatives and never a pair: the Bot API refuses `getUpdates`
+ * outright while a webhook is set, so a process that did both would spend its
+ * life in a 409 loop and the approver's tap would land on whichever half was
+ * lucky.
+ */
+export type TelegramTransport = "poll" | "webhook";
+/**
+ * Why a transport claim was refused. Frozen, per SPEC §11.1 invariant 6.
+ *
+ * One code, because there is one fact: this channel is already receiving
+ * updates by the other transport.
+ */
+export declare const TELEGRAM_TRANSPORT_REFUSAL_CODES: readonly ["transport-conflict"];
+export type TelegramTransportRefusalCode = (typeof TELEGRAM_TRANSPORT_REFUSAL_CODES)[number];
+export type TelegramTransportClaim = {
+    ok: true;
+    transport: TelegramTransport;
+} | {
+    ok: false;
+    code: TelegramTransportRefusalCode;
+    message: string;
+};
+/**
+ * The in-process half of "long-poll and webhook are mutually exclusive"
+ * (APRV-424).
+ *
+ * It is a belt on the braces and says so. The exclusion that matters is per
+ * BOT and lives above this class, where a process can ask the Bot API
+ * (`getWebhookInfo`) and the per-machine ownership registry who else is
+ * receiving this bot's updates; a channel object knows only about itself.
+ * What this rules out is the one failure a caller could cause here and
+ * nowhere else: feeding one channel instance from both a poll loop and an
+ * HTTP handler, where `handleUpdate`'s single ack slot and the delivery maps
+ * would be written by two arrivals nobody ordered.
+ */
+export declare class TelegramTransportError extends Error {
+    readonly code: TelegramTransportRefusalCode;
+    constructor(message: string);
+}
 export interface TelegramListenOptions {
     /** Process exactly one successful `getUpdates` batch, then return. */
     once?: boolean;
@@ -1206,6 +1366,17 @@ export interface TelegramListenOptions {
      * failure mode this loop exists to rule out.
      */
     beforePoll?: () => Promise<void>;
+    /**
+     * What the caller knows about who else might be polling this bot (APRV-390).
+     *
+     * Consulted only when a poll fails with the Bot API's 409, and appended to
+     * the one line that failure produces. The CLI builds it from the per-machine
+     * ownership registry (`core/channel-owner.ts`), so this class keeps no
+     * knowledge of instances, directories or files — it asks the question and
+     * prints the caller's answer, the same arrangement {@link
+     * TelegramConfig.describeAction} uses for the log.
+     */
+    conflictAdvice?: () => string | null;
 }
 /**
  * What {@link TelegramChannel.notifyBatch} did with a set (APRV-115).
@@ -1299,11 +1470,60 @@ export declare class TelegramChannel implements TestableChannel {
     private readonly digests;
     /** "All" nonce -> the digest message it was issued for. */
     private readonly allNonces;
+    /**
+     * Action keys whose card this process disarmed on a tap the gate did NOT
+     * settle (APRV-442): a refusal (`sender-unmapped`, a budget, an unattested
+     * policy, anything `ok: false`) or a handler that threw. Drained by
+     * {@link takeReleased}.
+     *
+     * The disarm is right and stays, and {@link refusedNonces} keeps it final:
+     * the refused card's bytes resolve to nothing, not even through the
+     * action-reference fallback to the card that replaces it. What the disarm
+     * must not do is leave the listener believing the REQUEST is on the
+     * approver's phone, which is what `DispatchState.delivered` goes on saying
+     * until something tells it otherwise. This set is that something: it names
+     * a card, never an outcome, and the listener re-derives from the verified
+     * log whether the request is still pending before it offers a new card.
+     * Nothing here decides, and losing it to a restart costs nothing, because a
+     * restarted listener re-sends everything pending anyway.
+     */
+    private readonly released;
+    /**
+     * Nonces of cards a refused or failed tap disarmed (APRV-442), oldest first,
+     * capped at {@link TELEGRAM_REFUSED_NONCE_CAP}.
+     *
+     * Without this, a released request's fresh card would give the refused
+     * card's bytes somewhere to go: the nonce misses, the action reference
+     * resolves to the new live card, and a Telegram redelivery of the refused
+     * tap (a webhook retry) or a client replaying the removed buttons would be
+     * refused again, append again, disarm the new card and cause another
+     * re-send, once per replay. A nonce in this set never takes the fallback, so
+     * a refused card stays exactly as dead as it was before APRV-442 and only
+     * the REQUEST is offered again. Forgetting an entry past the cap degrades to
+     * the fallback, whose tap the gate still judges in full: volume, never a
+     * decision.
+     */
+    private readonly refusedNonces;
     private rendered;
     private offset;
     private counter;
     private stopped;
     private inFlight;
+    /**
+     * The transport this channel has started receiving updates by, or `null`
+     * before the first one (APRV-424). Sticky for the life of the object: a
+     * process that stopped polling has not stopped being a poller, and the
+     * question this answers is which arrival path owns the maps below.
+     */
+    private transport;
+    /**
+     * Everything {@link redact} scrubs out of anything that leaves this class.
+     *
+     * The bot token from construction, plus any secret a later call was handed:
+     * {@link registerWebhook} adds the `secret_token` before it sends it, so a
+     * Bot API error quoting the request cannot put it on an operator's terminal.
+     */
+    private readonly secrets;
     private readonly counters;
     constructor(config: TelegramConfig);
     onDecision(handler: (decision: ChannelDecision) => DecisionOutcome): void;
@@ -1459,6 +1679,28 @@ export declare class TelegramChannel implements TestableChannel {
      * a decided one is not that.
      */
     private disarm;
+    /**
+     * How long after delivery the request behind a prompt can still be decided,
+     * on this process's clock, or `null` when nothing bounds it (APRV-423, second
+     * review pass).
+     *
+     * The SHORTER of two bounds, each of which is at or past the gate's own
+     * lapse, so the sweep never forgets a button a decision could still reach:
+     *
+     * - the request's `ttl_remaining_ms`, computed by the listener from the
+     *   verified log against the window the gate judges by (the policy's TTL
+     *   narrowed by the harness cap the requesting hook declared). It was
+     *   measured at tagging time, and delivery is at or after tagging, so
+     *   counting it from delivery ends at or after the real lapse;
+     * - the policy's own TTL ({@link TelegramConfig.approvalTtlMs}), counted from
+     *   delivery, which is at or after the `approval.requested` it really runs
+     *   from. This was the only bound before APRV-423 and it stays as one.
+     *
+     * A request neither bounds is decidable forever, and its entry is dropped
+     * only on an observed settlement. This channel still reads no policy and no
+     * log: both numbers arrive computed, by the verb and by the tagger.
+     */
+    private retentionWindowMs;
     /**
      * Drop the delivery bookkeeping no callback can still be honoured against
      * (APRV-135).
@@ -1552,6 +1794,28 @@ export declare class TelegramChannel implements TestableChannel {
      * {@link Channel} interface names. Its wording is unchanged.
      */
     retract(deliveryId: DeliveryId, reason: string, actionKey?: string): Promise<void>;
+    /**
+     * The action keys whose card a refused or failed tap disarmed since the last
+     * call, and forget them (APRV-442).
+     *
+     * The listener's dispatch cycle calls this once per cycle and offers a fresh
+     * card for every key the verified log still calls pending. It is a statement
+     * about this process's cards and nothing else: it carries no decision, no
+     * sender and no outcome, and a key in it that the log has since settled is
+     * simply not offered.
+     */
+    takeReleased(): string[];
+    /**
+     * Mark `delivery`'s card dead and its request released, BEFORE the
+     * annotation that disarms it (APRV-442).
+     *
+     * Every nonce still armed for this request on this message is recorded in
+     * {@link refusedNonces}, together with the nonce the tap carried (which
+     * differs when the tap came from an earlier copy through the fallback), so
+     * none of those bytes can later resolve to the fresh card. On a digest only
+     * this member's nonce is taken: its siblings stay armed on the digest.
+     */
+    private release;
     /**
      * Send one plain message that carries no question (APRV-196).
      *
@@ -1563,6 +1827,24 @@ export declare class TelegramChannel implements TestableChannel {
      * HTML-mode message is.
      */
     announce(lines: string[]): Promise<DeliveryId>;
+    /**
+     * Which bot this token is, from one `getMe` (APRV-390).
+     *
+     * `getMe` is the only Bot API call that answers it, and it is the call
+     * `approval doctor` and `approval setup channel telegram` already make for
+     * the same reason: it mutates nothing, sends nothing, and acknowledges
+     * nothing. In particular it is NOT `getUpdates`, so asking who this bot is
+     * consumes no update and steals no pending tap from a listener that is
+     * already running — which matters here above all, because the answer is
+     * what decides whether this process is allowed to poll at all.
+     *
+     * Throws {@link TelegramApiError} like every other call; the caller decides
+     * whether an unreachable Bot API is a refusal or a shrug.
+     */
+    identify(): Promise<{
+        id: string;
+        username: string;
+    }>;
     /**
      * Long-poll `getUpdates` until {@link stop} is called (or one batch, with
      * `once`).
@@ -1588,6 +1870,99 @@ export declare class TelegramChannel implements TestableChannel {
      * what {@link listen} catches and retries.
      */
     pollOnce(): Promise<TelegramPollResult>;
+    /**
+     * Which update types this channel asks for, on either transport (APRV-424).
+     *
+     * APRV-216. `message` is asked for only while a command handler is
+     * registered: see {@link onCommand} for why a listener that reads messages
+     * nobody asked for would break `approval setup channel telegram`'s chat
+     * discovery. APRV-299 adds the second reason to read messages: a `loved` or
+     * `disliked` on a review card collects the human's words as a REPLY, because
+     * an inline keyboard has no text input.
+     *
+     * One function since APRV-424, because `setWebhook` takes the same list as
+     * `getUpdates` and two spellings of it would be two answers to "what does
+     * this listener read" — with the webhook's answer frozen at registration
+     * time, where nobody would look for it.
+     */
+    allowedUpdates(): string[];
+    /**
+     * One update, from whichever transport carried it (APRV-424).
+     *
+     * The whole of what the webhook adds is the ARRIVAL. Everything a tap then
+     * passes through — the chat check, `senderOf`, the checkpoint and review
+     * parsers, the resolution ladder, the early ack, `this.handler` and the
+     * annotation written from the record the gate appended — is
+     * {@link handleUpdate}, called from here and from {@link pollOnce}, and
+     * there is no second copy of any of it. `tests/telegram-webhook.test.ts`
+     * drives one callback through both entry points and compares the records the
+     * log ends up holding.
+     *
+     * The sweep is `pollOnce`'s, for `pollOnce`'s reason: this is the moment the
+     * process is about to be idle, and a channel that only ever wakes for taps
+     * would otherwise never run one.
+     */
+    deliverUpdate(update: unknown): Promise<TelegramPollResult>;
+    /** The per-update bookkeeping both transports do, before `handleUpdate`. */
+    private intake;
+    /**
+     * Bind this channel to one transport, or say which one already holds it
+     * (APRV-424).
+     *
+     * Idempotent for the transport already claimed, so a webhook server that
+     * claims at start-up and then delivers, or a driver calling `pollOnce` in a
+     * loop, pays nothing. Not released by {@link stop}: a process that stopped
+     * polling has not stopped being a poller, and re-pointing a live channel's
+     * delivery maps at a second arrival path is the state this exists to refuse.
+     */
+    claimTransport(transport: TelegramTransport): TelegramTransportClaim;
+    /** {@link claimTransport}, for the paths where a refusal is a caller's bug. */
+    private claimOrThrow;
+    /**
+     * Point this bot's updates at `url`, and require `secret` on every post.
+     *
+     * Three properties, and each is a refusal to be clever:
+     *
+     * - **The secret is Telegram's own mechanism**, `secret_token`, echoed back
+     *   on every delivery in the `X-Telegram-Bot-Api-Secret-Token` header. The
+     *   receiver compares it and refuses anything else, so a URL that leaks (a
+     *   proxy log, a referrer, a screenshot) is a URL that still decides
+     *   nothing.
+     * - **It is redacted from this moment on.** The value is added to the
+     *   channel's secret list BEFORE the call, so a Bot API error that quotes
+     *   the request cannot print it.
+     * - **Pending updates are kept.** `drop_pending_updates` is left false:
+     *   taps that arrived while the process was down are the approver's answers,
+     *   and the gate is what decides whether they are still honourable.
+     */
+    registerWebhook(url: string, secret: string): Promise<void>;
+    /**
+     * Take this bot's webhook away, so `getUpdates` works again.
+     *
+     * Called on a clean stop of the webhook runner. Pending updates are kept for
+     * {@link registerWebhook}'s reason: the next process to start — a poller or
+     * another webhook — is entitled to the taps that arrived in between.
+     *
+     * `timeoutMs` is what the stop path passes, and it is shorter than this
+     * channel's ordinary request timeout on purpose (APRV-424, second review,
+     * note 6). A stop already waits for the receiver to drain, and an operator
+     * pressing Ctrl-C a second time is asking for the process to end: half a
+     * minute of an unreachable Bot API on top of that reads as a hang, and the
+     * webhook it failed to remove is reported rather than silently retried.
+     */
+    deleteWebhook(timeoutMs?: number): Promise<void>;
+    /**
+     * What the Bot API says is receiving this bot's updates right now.
+     *
+     * The one authority on the question, and the reason it is asked at start-up
+     * by both transports: the ownership registry knows about processes on THIS
+     * machine, and a webhook registered from a laptop in another timezone is
+     * still a webhook swallowing every tap this poller is waiting for.
+     */
+    webhookInfo(): Promise<{
+        url: string;
+        pendingUpdateCount: number;
+    }>;
     /**
      * Exactly one `answerCallbackQuery` per callback query, on every path
      * (APRV-196).
@@ -1807,7 +2182,14 @@ export declare class TelegramChannel implements TestableChannel {
      * settled, so a member still in the map is one still armed on a live message.
      */
     private liveDeliveryFor;
-    /** Replace the token with a placeholder anywhere it appears in `text`. */
+    /**
+     * Replace every secret this channel holds with a placeholder in `text`.
+     *
+     * The bot token always, and since APRV-424 the webhook `secret_token` too,
+     * from the moment {@link registerWebhook} is handed it. Both are values that
+     * only ever travel TO the Bot API, so anything coming back that quotes one
+     * is a diagnostic about to print a credential.
+     */
     private redact;
     private describe;
     /**