@axorum/client 0.0.0-stage → 1.1.0

package/dist/authorize.js

@@ -0,0 +1,947 @@
+/**
+ * The one-call `authorize`: who is paying, whether they may, and the pin loop that gets
+ * the ledger's answer.
+ *
+ * Everything here but {@link runAuthorize} is a pure function, testable without a
+ * socket. Re-sending a request that failed in transit is the client's job, under
+ * `authorize`'s own policy and one deadline for the call; see `retry.ts`.
+ *
+ * @packageDocumentation
+ */
+import { ApiError, AttestationError, AxorumError, CommitUnavailableError, ConnectError, DeadlineExceededError, DecodeError, IdempotencyWindowError, EndpointsExhaustedError, InvalidAgentError, NoActivePolicyError, NotPrimaryError, StaleIdempotencyKeyError, StalePolicyError, RateLimitedError, TransactionReusedError, TransportError, UnexpectedResponseError, UnknownAgentError, } from "./errors.js";
+import { agentUriProblem } from "./agent-uri.js";
+import { describeAttempt, rotationLabel } from "./failover.js";
+import { pinIntent } from "./intent.js";
+import { DEFAULT_CHART_V1 } from "./chart.js";
+import { ATTESTATION_MIN_REMAINING_MS, attestationExpiryMs, attestationFreshness, formatUtcMs, submissionDeadline, } from "./freshness.js";
+import { ensureFresh } from "./idempotency.js";
+import { AUTHORIZE_RETRY_POLICY, pause, retryLabel } from "./retry.js";
+import { planPayment } from "./payment.js";
+import { isKnownSubstrateCause } from "./refusal.js";
+/**
+ * The paying agent: its `agent://` URI and where its attestation comes from.
+ *
+ * The URI must be in **canonical form**: the complete grammar the service parses, with a
+ * lowercase scheme and host, a port without leading zeros, an IPv4 address with no leading
+ * zero in an octet, an IPv6 address as RFC 5952 writes it, and no query or fragment. A keyed payment derives its id from these exact bytes, so
+ * one spelling per agent is what makes this SDK and the Rust one derive the same id. The
+ * service answers `unknown_agent` for a well-formed URI no party is bound to.
+ *
+ * ```ts
+ * import { Agent } from "@axorum/client";
+ *
+ * // A static token:
+ * const buyer = new Agent("agent://acme.com/agent/buyer_01h455vb4pex5vsknk084sn02q", paseto);
+ *
+ * // Or a source asked on every submission, so an expiring token is refreshed:
+ * const refreshing = new Agent(
+ *   "agent://acme.com/agent/buyer_01h455vb4pex5vsknk084sn02q",
+ *   () => issuer.mint(),
+ * );
+ * ```
+ */
+export class Agent {
+    /** The `agent://` URI, in canonical form: exactly the string the constructor accepted. */
+    uri;
+    #attestation;
+    /**
+     * @throws {InvalidAgentError} If `uri` is not an `agent://` URI in canonical form (its
+     *   `canonical` then names the form to pass, when there is one), or a static
+     *   attestation is not a PASETO v4.public token.
+     */
+    constructor(uri, attestation) {
+        const refused = agentUriProblem(uri);
+        if (refused !== undefined) {
+            throw new InvalidAgentError(refused.canonical === undefined
+                ? `'${uri}' is not an agent:// URI (${refused.reason}); pass the URI exactly as your ` +
+                    `operator bound it, for example agent://acme.com/agent/buyer_01h455vb4pex5vsknk084sn02q`
+                : `'${uri}' is not a canonical agent:// URI (${refused.reason}); pass '${refused.canonical}'`, refused.canonical);
+        }
+        if (typeof attestation === "string") {
+            const problem = attestationProblem(attestation) ?? claimsProblem(attestation);
+            if (problem !== undefined) {
+                throw new InvalidAgentError(problem);
+            }
+        }
+        this.uri = uri;
+        this.#attestation = attestation;
+    }
+    /**
+     * The attestation for one submission: the token, or a fresh one from the source,
+     * with at least {@link ATTESTATION_MIN_REMAINING_MS} left before its `exp`.
+     *
+     * The service allows no leeway on `exp`, and a submission may be re-sent for up to
+     * its budget, so a token with less left could expire between two sends of the same
+     * payment. A source whose token is that close is asked once more; nothing is sent
+     * unless a token is fresh.
+     *
+     * @param now - The current time in epoch milliseconds; the system clock by default.
+     * @throws {AuthorizeError} Of kind `attestation_expiring` if no token had enough time
+     *   left, or `attestation_unavailable` if the source failed or returned a token whose
+     *   claims cannot be read.
+     */
+    async attestation(transaction, now = Date.now) {
+        const token = await this.#ask(transaction);
+        const freshness = judgeToken(transaction, token, now());
+        if (freshness.state === "fresh") {
+            return token;
+        }
+        if (typeof this.#attestation === "string") {
+            throw new AuthorizeError(transaction, { kind: "attestation_expiring", expiresAt: freshness.expiresAt });
+        }
+        const again = await this.#ask(transaction);
+        const refreshed = judgeToken(transaction, again, now());
+        if (refreshed.state === "fresh") {
+            return again;
+        }
+        throw new AuthorizeError(transaction, { kind: "attestation_expiring", expiresAt: refreshed.expiresAt });
+    }
+    /** One token from the static value or the source, checked for shape. */
+    async #ask(transaction) {
+        if (typeof this.#attestation === "string") {
+            return this.#attestation;
+        }
+        let token;
+        try {
+            token = await this.#attestation();
+        }
+        catch (cause) {
+            throw new AuthorizeError(transaction, { kind: "attestation_unavailable" }, cause);
+        }
+        const problem = attestationProblem(token);
+        if (problem !== undefined) {
+            throw new AuthorizeError(transaction, { kind: "attestation_unavailable" }, new InvalidAgentError(problem));
+        }
+        return token;
+    }
+}
+/**
+ * The token's freshness at `nowMs`, with an unreadable token already thrown as
+ * `attestation_unavailable`.
+ */
+function judgeToken(transaction, token, nowMs) {
+    const freshness = attestationFreshness(token, nowMs, ATTESTATION_MIN_REMAINING_MS);
+    if (freshness.state === "unreadable") {
+        throw new AuthorizeError(transaction, { kind: "attestation_unavailable" }, new InvalidAgentError(freshness.problem));
+    }
+    return freshness;
+}
+/** Why a token's claims cannot be read, or `undefined`; independent of the time. Pure. */
+function claimsProblem(token) {
+    const freshness = attestationFreshness(token, 0, 0);
+    return freshness.state === "unreadable" ? freshness.problem : undefined;
+}
+/** Why `token` is not a usable PASETO v4.public token, or `undefined`. Pure. */
+export function attestationProblem(token) {
+    if (/\s|\p{Cc}/u.test(token)) {
+        return "the attestation contains whitespace or a control character; pass the token alone";
+    }
+    if (!token.startsWith("v4.public.")) {
+        return "the attestation is not a PASETO v4.public token (it must start with 'v4.public.')";
+    }
+    if (token.length === "v4.public.".length) {
+        return "the attestation has no payload after 'v4.public.'";
+    }
+    return undefined;
+}
+/** The verdicts under which a posted payment is allowed. */
+const ALLOWING = new Set(["Permitted", "ObligatedPending", "ObligatedFulfilled"]);
+/**
+ * The answer an outcome gives, or `undefined` for one no agent payment can produce (a
+ * posted `ForbiddenRecorded`, an unposted allowing verdict, or a refusal that does not
+ * say why). Pure; fails closed: the refusal is always the service's, never invented.
+ */
+export function judge(outcome) {
+    const receipt = outcome.receipt;
+    const replayed = outcome.replayed === true;
+    if (outcome.posted) {
+        return ALLOWING.has(outcome.verdict)
+            ? {
+                allowed: true,
+                transaction: outcome.transaction,
+                obligations: outcome.obligations_pending,
+                receipt,
+                replayed,
+                outcome,
+            }
+            : undefined;
+    }
+    if (outcome.verdict !== "ForbiddenRejected" || outcome.refusal === undefined) {
+        return undefined;
+    }
+    return {
+        allowed: false,
+        transaction: outcome.transaction,
+        refusal: outcome.refusal,
+        receipt,
+        replayed,
+        outcome,
+    };
+}
+/**
+ * Whether the justification recorded for this answer's transaction is `text`: its
+ * SHA-256 equals the answer's `justification_hash`. On a replay the recorded
+ * justification is the one the first submission carried, so a re-drive that reworded
+ * it resolves `false` here. Async only because it hashes with WebCrypto.
+ *
+ * ```ts
+ * const answer = await axorum.authorize(buyer, order);
+ * if (answer.replayed && !(await justificationMatches(answer, order.justification))) {
+ *   log.warn("the ledger kept the first justification, not this one");
+ * }
+ * ```
+ */
+export async function justificationMatches(answer, text) {
+    return (await justificationHash(text)) === answer.outcome.justification_hash;
+}
+/** The lowercase-hex SHA-256 of `text`'s UTF-8 bytes, as the service hashes it. */
+export async function justificationHash(text) {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+    return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * What a {@link AuthorizeFailure | `not_submitted`} failure always says: this call sent
+ * nothing, but an earlier ambiguous one may still land.
+ */
+export const NOT_SUBMITTED_CAVEAT = "If an earlier call with this key was ambiguous, the transaction may still commit; retry with the same key and the server will replay.";
+/** How many policy rotations one call absorbs by re-pinning. */
+export const MAX_AUTHORIZE_PINS = 3;
+/**
+ * An authorize call that got no answer. Carries the payment's transaction id, which is
+ * what makes recovery safe: re-drive the **same** {@link Payment} and a payment that
+ * already committed replays its answer instead of paying twice.
+ *
+ * ```ts
+ * try {
+ *   const answer = await axorum.authorize(buyer, lunch);
+ * } catch (error) {
+ *   if (error instanceof AuthorizeError && error.retryable) {
+ *     queue.later(lunch); // same Payment, same transaction id
+ *   } else if (error instanceof AuthorizeError && error.needsFreshAttestation) {
+ *     await refreshToken();
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export class AuthorizeError extends AxorumError {
+    code = "authorize";
+    /** The payment's transaction id. */
+    transaction;
+    /** What went wrong. */
+    failure;
+    /** The underlying failure, when there was one. */
+    cause;
+    constructor(transaction, failure, cause) {
+        super(`authorize ${transaction}: ${describeFailure(failure, cause)}`, cause instanceof AxorumError ? cause.status : null, cause instanceof AxorumError ? cause.body : null);
+        this.transaction = transaction;
+        this.failure = failure;
+        this.cause = cause;
+    }
+    /** The failure's kind, for a `switch`. */
+    get kind() {
+        return this.failure.kind;
+    }
+    /**
+     * Whether re-driving the same payment later may get an answer: after `indeterminate`,
+     * when the answer was not received, and after `not_submitted`, when this call
+     * submitted nothing. Every other kind fails identically on a re-drive until something
+     * outside the call changes.
+     */
+    get retryable() {
+        return this.failure.kind === "indeterminate" || this.failure.kind === "not_submitted";
+    }
+    /** Whether the fix is a fresh attestation. */
+    get needsFreshAttestation() {
+        return this.failure.kind === "attestation_rejected" || this.failure.kind === "attestation_expiring";
+    }
+}
+/** What each failure means and what to do next. Pure. */
+function describeFailure(failure, cause) {
+    const said = cause instanceof Error ? ` (${cause.message})` : "";
+    switch (failure.kind) {
+        case "attestation_rejected":
+            return (`the service rejected the attestation${said}; obtain a fresh token from your issuer and ` +
+                `re-drive the same payment, which replays the answer if an earlier send of it committed`);
+        case "attestation_unavailable":
+            return `the attestation source failed${said}; nothing was sent. Fix the source, then re-drive the same payment`;
+        case "attestation_expiring":
+            return (`the attestation expires at ${failure.expiresAt}, less than ` +
+                `${ATTESTATION_MIN_REMAINING_MS / 1000} s from now, and no fresher token was available; ` +
+                `nothing was sent. Issue tokens valid for at least 5 minutes (15 to 60 is typical), check ` +
+                `this host's clock against NTP, then re-drive the same payment`);
+        case "unknown_agent":
+            return `no party is bound to this agent${said}; ask your operator to bind the agent:// URI, or check it for a typo`;
+        case "no_active_policy":
+            return `no policy is in force${said}; an operator must activate one before any payment can be judged`;
+        case "currency_not_declared":
+            return (`${failure.currency} is not a currency this deployment declared${said}; nothing was recorded. ` +
+                `An operator must declare it (\`axorum currency declare --code ${failure.currency} --exponent ` +
+                `<minor units>\`, or [[currencies]] in the serve config), then open the default chart in it`);
+        case "chart_not_provisioned":
+            return (`the default chart is not open in ${failure.currency}${said}; nothing was recorded. An ` +
+                `operator must open it (\`axorum chart provision --currency ${failure.currency}\`, or ` +
+                `[default_chart] in the serve config)`);
+        case "unknown_payee":
+            return (`the payee ${failure.payee} is not in the counterparty registry the policy in force reads${said}; ` +
+                `nothing was recorded. An operator must import it with approved: false to have it refused, or ` +
+                `approved: true to allow it`);
+        case "policy_contract":
+            return `the policy in force does not accept this payment's shape${said}; it must declare \`${DEFAULT_CHART_V1.declaration}\``;
+        case "transaction_reused":
+            return (`this transaction id already committed with different content${said}; nothing was written. ` +
+                `Create a new payment for a new payment, or re-drive the original unchanged`);
+        case "key_window_unstated":
+            return ((failure.reason === "malformed"
+                ? `the service's \`${failure.header}\` header carries ${JSON.stringify(failure.value)}, ` +
+                    "which states no idempotency window"
+                : "the service states no idempotency window (its writer could not answer)") +
+                ", so a key from your records cannot be aged against it; nothing was sent. Read the " +
+                "transaction to learn whether it landed, and authorize a new payment only if it did not, " +
+                "or retry once the service is healthy");
+        case "stale_key":
+            return failure.reason === "unclocked"
+                ? `the service runs no heartbeat (tick_interval_ms is 0), so its idempotency window ` +
+                    `(${failure.windowTicks} ticks) does not follow the wall clock and vouches for no key ` +
+                    "from your records; nothing was sent. Reconcile first: read the transaction to learn " +
+                    "whether it landed, and authorize a new payment only if it did not. To resend a key " +
+                    "from your records, ask the service's operator to re-enable its heartbeat " +
+                    "(tick_interval_ms above 0)"
+                : `this payment's key was minted ${Math.floor((failure.ageMs ?? 0) / 1000)} s ago, past the ` +
+                    `service's ${failure.windowSeconds} s idempotency window, so the ledger may have ` +
+                    "forgotten it and would apply it again; nothing was sent. Read the transaction to " +
+                    "learn whether it landed, and authorize a new payment only if it did not";
+        case "keyed_for_another_agent":
+            return (`this payment's key was derived for ${failure.keyedFor}, not ${failure.agent}; nothing was ` +
+                `sent. Build the payment with keyedPayment for the agent that pays`);
+        case "capacity":
+            return failure.retryAfterMs === null
+                ? `the ledger is at a capacity bound${said}; an operator must raise it`
+                : `the ledger is at a capacity bound${said}; it may make room in ` +
+                    `${Math.ceil(failure.retryAfterMs / 1000)} s, or an operator can raise it`;
+        case "stale_policy":
+            return (`the policy in force kept changing under the call (last pinned ${failure.pinned}, now ` +
+                `${failure.active}); nothing was written. Authorize again once policy rotation settles`);
+        case "indeterminate":
+            return (`the ledger's answer was not received (${describeCause(failure.lastCause)}); the payment may ` +
+                `or may not have committed. Re-drive the same payment to find out; it cannot pay twice`);
+        case "not_submitted":
+            return (`nothing from this call was submitted: ${describeUnsent(failure.cause)}` +
+                (failure.tried.length === 0 ? "" : ` (tried: ${failure.tried.map(describeAttempt).join(", ")})`) +
+                `; authorize the same Payment again. ${NOT_SUBMITTED_CAVEAT}`);
+        case "unexpected_verdict":
+            if (failure.outcome.verdict === "ForbiddenRejected" && failure.outcome.refusal === undefined) {
+                return ("the ledger refused the payment without saying why, which a service on the current " +
+                    "contract never does; do not pay, and report it to your operator");
+            }
+            return (`the ledger answered with verdict ${failure.outcome.verdict} (posted: ${failure.outcome.posted}), ` +
+                `which no agent payment can produce; do not pay, and report it to your operator`);
+        case "rejected":
+            return (`the service refused the request (${failure.status} ${failure.body.error}` +
+                `${failure.body.cause === undefined ? "" : `, cause ${failure.body.cause}`}): ${failure.body.message}`);
+        case "undecodable":
+            return `the ledger answered but the answer did not decode${said}; it may have committed, so read the transaction back before paying`;
+        case "unexpected":
+            return (`a ${failure.status ?? "non-HTTP"} failure came back that is not from the Axorum service${said}; ` +
+                `check what sits between you and the service`);
+    }
+}
+/** One line for what a `not_submitted` call ended on, as the Rust SDK words it. Pure. */
+function describeUnsent(cause) {
+    switch (cause.kind) {
+        case "connect":
+            return `no connection opened (${cause.message})`;
+        case "rate_limited":
+            return `429 rate limited (${cause.message})`;
+        case "unseeded":
+            return `the primary has not seeded its idempotency index (503 idempotency_unseeded: ${cause.message})`;
+        case "seed_refused":
+            return (`the ledger refused the primary's idempotency seed (500 idempotency_seed_refused: ` +
+                `${cause.message}); ask your operator to fail the primary over`);
+        case "not_normal":
+            return `the replica was in a view change or a recovery (503 not_normal: ${cause.message})`;
+        case "archive_pressure":
+            return (`the primary's local archive is behind (503 archive_pressure: ${cause.message}); ` +
+                `ask your operator to check the archiver`);
+        case "quarantined":
+            return (`the node is quarantined after a replay divergence (503 quarantined: ${cause.message}); ` +
+                `ask your operator to resolve the quarantine`);
+        case "proposal_refused":
+            return (`the node refused the proposal (500 proposal_refused: ${cause.message}); ` +
+                `ask your operator to check the node's logs`);
+        case "deadline_exceeded":
+            return `the time budget ran out ${Math.round(cause.elapsedMs)} ms in, before the payment was sent`;
+        case "other":
+            return cause.message;
+    }
+}
+/** One line for a cause. Pure. */
+function describeCause(cause) {
+    switch (cause.kind) {
+        case "connect":
+            return `connect: ${cause.message}`;
+        case "rate_limited":
+            return `429 rate limited: ${cause.message}`;
+        case "transport":
+            return `transport: ${cause.message}`;
+        case "not_primary":
+            return `421 not_primary${cause.reason === null ? "" : ` (${cause.reason})`}`;
+        case "commit_unavailable":
+            return `503 commit_unavailable${cause.reason === null ? "" : ` (${cause.reason})`}`;
+        case "unavailable":
+            return cause.code === null ? `${cause.status} from the service or its proxy` : `${cause.status} ${cause.code}`;
+        case "deadline_exceeded":
+            return `the time budget ran out ${Math.round(cause.elapsedMs)} ms into the request, before it could be sent`;
+        case "earlier_attempt_in_doubt":
+            return (`an earlier attempt ended without an answer (${cause.earlier}) and may have committed; ` +
+                `the call then ended with: ${cause.last}`);
+    }
+}
+/**
+ * The `422` cause that means the default chart is not open in the payment's currency.
+ * Typed against {@link KnownSubstrateCause}, so a token the contract does not document
+ * does not compile.
+ */
+const CHART_NOT_PROVISIONED_CAUSE = "unknown_account";
+/** The `422` cause that means the payment's currency was never declared. */
+const CURRENCY_NOT_DECLARED_CAUSE = "undeclared_currency";
+/** The `422` cause that means the payee is not in the counterparty registry. */
+const UNKNOWN_PAYEE_CAUSE = "unknown_counterparty";
+/** The `422` causes that mean the policy does not declare the payment's action. */
+const POLICY_CONTRACT_CAUSES = [
+    "undeclared_action",
+    "missing_param",
+    "unexpected_param",
+    "param_type_mismatch",
+];
+/**
+ * Decides what to do about a failed request. Pure: the whole table.
+ *
+ * Re-pinned: a `409` stale pin. Unanswered (`indeterminate`): transport failures, `421`,
+ * `502`/`503`/`504`, and a request the deadline left no time to send. Everything else is
+ * a typed failure.
+ */
+export function classify(error, pay) {
+    const fail = (failure) => ({ action: "fail", failure });
+    if (error instanceof EndpointsExhaustedError) {
+        return classify(error.last, pay);
+    }
+    if (error instanceof ConnectError) {
+        return { action: "unanswered", cause: { kind: "connect", message: error.message } };
+    }
+    if (error instanceof RateLimitedError) {
+        return { action: "unanswered", cause: { kind: "rate_limited", message: error.detail } };
+    }
+    if (error instanceof TransportError) {
+        return { action: "unanswered", cause: { kind: "transport", message: error.message } };
+    }
+    if (error instanceof DeadlineExceededError) {
+        return { action: "unanswered", cause: { kind: "deadline_exceeded", elapsedMs: error.elapsedMs } };
+    }
+    if (error instanceof NotPrimaryError) {
+        return { action: "unanswered", cause: { kind: "not_primary", reason: error.reason } };
+    }
+    if (error instanceof CommitUnavailableError) {
+        return { action: "unanswered", cause: { kind: "commit_unavailable", reason: error.reason } };
+    }
+    if (error instanceof StalePolicyError) {
+        return { action: "repin", active: error.active, pinned: error.pinned };
+    }
+    if (error instanceof TransactionReusedError) {
+        return fail({
+            kind: "transaction_reused",
+            storedContentHash: error.storedContentHash ?? null,
+            submittedContentHash: error.submittedContentHash ?? null,
+        });
+    }
+    if (error instanceof NoActivePolicyError) {
+        return fail({ kind: "no_active_policy" });
+    }
+    if (error instanceof UnknownAgentError) {
+        return fail({ kind: "unknown_agent" });
+    }
+    if (error instanceof AttestationError) {
+        return fail({ kind: "attestation_rejected" });
+    }
+    if (error instanceof DecodeError) {
+        return fail({ kind: "undecodable" });
+    }
+    if (error instanceof UnexpectedResponseError) {
+        return error.status !== null && error.status >= 502 && error.status <= 504
+            ? { action: "unanswered", cause: { kind: "unavailable", status: error.status, code: null } }
+            : fail({ kind: "unexpected", status: error.status });
+    }
+    if (error instanceof ApiError) {
+        return classifyBody(error.status ?? 0, error.body, error.retryAfterMs, pay);
+    }
+    return fail({ kind: "unexpected", status: error instanceof AxorumError ? error.status : null });
+}
+/** The documented error bodies with no dedicated class. Pure. */
+function classifyBody(status, body, retryAfterMs, pay) {
+    const fail = (failure) => ({ action: "fail", failure });
+    const cause = body.cause;
+    if (status === 409 && body.error === "transaction_reused") {
+        return fail({
+            kind: "transaction_reused",
+            storedContentHash: body.stored_content_hash ?? null,
+            submittedContentHash: body.submitted_content_hash ?? null,
+        });
+    }
+    if (status === 507) {
+        return fail({ kind: "capacity", retryAfterMs });
+    }
+    if (status >= 502 && status <= 504) {
+        return { action: "unanswered", cause: { kind: "unavailable", status, code: body.error } };
+    }
+    if (status === 422 && cause !== undefined && isKnownSubstrateCause(cause)) {
+        if (cause === CURRENCY_NOT_DECLARED_CAUSE) {
+            return fail({ kind: "currency_not_declared", currency: pay.amount.currency });
+        }
+        if (cause === CHART_NOT_PROVISIONED_CAUSE) {
+            return fail({ kind: "chart_not_provisioned", currency: pay.amount.currency });
+        }
+        if (cause === UNKNOWN_PAYEE_CAUSE) {
+            return fail({ kind: "unknown_payee", payee: pay.payee });
+        }
+        if (POLICY_CONTRACT_CAUSES.includes(cause)) {
+            return fail({ kind: "policy_contract" });
+        }
+    }
+    return fail({ kind: "rejected", status, body });
+}
+/**
+ * The cause of a `not_submitted` call that ended on `error`, or `undefined` when `error`
+ * does not prove its attempt {@link AxorumError.wroteNothing | wrote nothing}. A call
+ * that moved between URLs ended on its last attempt's failure. Pure.
+ */
+export function unsent(error) {
+    const last = error instanceof EndpointsExhaustedError ? error.last : error;
+    if (!(last instanceof AxorumError) || !last.wroteNothing) {
+        return undefined;
+    }
+    if (last instanceof ConnectError) {
+        return { kind: "connect", message: last.message };
+    }
+    if (last instanceof RateLimitedError) {
+        return { kind: "rate_limited", message: last.detail };
+    }
+    if (last instanceof DeadlineExceededError) {
+        return { kind: "deadline_exceeded", elapsedMs: last.elapsedMs };
+    }
+    if (last instanceof ApiError && last.code === "idempotency_unseeded") {
+        return { kind: "unseeded", message: last.body.message };
+    }
+    if (last instanceof ApiError && last.code === "idempotency_seed_refused") {
+        return { kind: "seed_refused", message: last.body.message };
+    }
+    if (last instanceof ApiError && last.code === "not_normal") {
+        return { kind: "not_normal", message: last.body.message };
+    }
+    if (last instanceof ApiError && last.code === "archive_pressure") {
+        return { kind: "archive_pressure", message: last.body.message };
+    }
+    if (last instanceof ApiError && last.code === "quarantined") {
+        return { kind: "quarantined", message: last.body.message };
+    }
+    if (last instanceof ApiError && last.code === "proposal_refused") {
+        return { kind: "proposal_refused", message: last.body.message };
+    }
+    return { kind: "other", message: last.message };
+}
+/**
+ * What to do about a failed request of the call, given the first attempt of the call
+ * left in doubt, if any, and every attempt `tried`, the last included: `not_submitted`
+ * exactly when `error` wrote nothing ({@link unsent}) and nothing was in doubt;
+ * {@link classify} otherwise, which the caller reads {@link afterDoubt}. Pure.
+ */
+export function dispose(error, pay, earlier, tried) {
+    const cause = earlier === undefined ? unsent(error) : undefined;
+    return cause === undefined
+        ? classify(error, pay)
+        : { action: "fail", failure: { kind: "not_submitted", tried, cause } };
+}
+/**
+ * How a call ends on a request that failed with `error`, given the first attempt of the
+ * call left in doubt, if any, and every attempt `tried`, the last included: its
+ * {@link dispose | disposition}, a failure read {@link afterDoubt | after the doubt}.
+ * Pure.
+ */
+export function conclude(error, pay, earlier, tried) {
+    const disposition = dispose(error, pay, earlier, tried);
+    switch (disposition.action) {
+        case "fail":
+            return afterDoubt(disposition.failure, earlier, error);
+        case "unanswered":
+            return afterDoubt({ kind: "indeterminate", lastCause: disposition.cause }, earlier, error);
+        case "repin":
+            return afterDoubt({ kind: "stale_policy", pinned: disposition.pinned, active: disposition.active }, earlier, error);
+    }
+}
+/**
+ * The failure an earlier attempt stands for, as far as the retry loop shows it: a
+ * re-sent status arrives without its body, so it reads as a body this client cannot
+ * vouch for ({@link UnexpectedResponseError}). Pure.
+ */
+function seen(reason) {
+    switch (reason.kind) {
+        case "connect":
+            return new ConnectError(retryLabel(reason));
+        case "status":
+            return new UnexpectedResponseError(reason.status, "");
+        case "timeout":
+            return new TransportError(retryLabel(reason));
+    }
+}
+/**
+ * Whether an attempt the transport sent again after `reason` may have committed: unless
+ * what it saw {@link AxorumError.wroteNothing | wrote nothing}. Only a connection that
+ * never opened is definite: a re-sent status arrives without its body, so even a `429`,
+ * a `421` or a `507` cannot show the code that would make it definite. Every other
+ * outcome, a status this version does not know included, is doubt. Pure; the same rule
+ * as the Rust SDK.
+ */
+export function leavesDoubt(reason) {
+    return !seen(reason).wroteNothing;
+}
+/**
+ * The `422 substrate_rejected` causes the service decides **before** it looks the
+ * transaction id up, so a re-sent submission whose first attempt committed can still be
+ * refused with them: `undeclared_currency` (the gateway's currency admission) and
+ * `amount_overflow` (the gateway's mandate-charge derivation).
+ */
+const DECIDED_BEFORE_REPLAY = ["undeclared_currency", "amount_overflow"];
+/**
+ * Whether `error` is the ledger's own answer about this transaction id, given after it
+ * looked the id up: `409 transaction_reused`, or a `422 substrate_rejected` whose cause
+ * is decided after that lookup (every cause but `undeclared_currency` and
+ * `amount_overflow`; `unknown_account`, `unknown_counterparty` and the action-contract
+ * causes are among them). Had an earlier attempt committed, the service would have
+ * answered with its replay instead, so the answer stands after an attempt in doubt.
+ * Pure.
+ */
+export function settlesTheId(error) {
+    if (error instanceof TransactionReusedError) {
+        return true;
+    }
+    if (!(error instanceof ApiError)) {
+        return false;
+    }
+    if (error.status === 409) {
+        return error.code === "transaction_reused";
+    }
+    const cause = error.body.cause;
+    return (error.status === 422 &&
+        error.code === "substrate_rejected" &&
+        (cause === undefined || !DECIDED_BEFORE_REPLAY.includes(cause)));
+}
+/**
+ * `failure`, given the first attempt of the call left in doubt, if any, and the error it
+ * came from. Once an earlier attempt is in doubt, an end that read alone says the payment
+ * did not land becomes `indeterminate`, cause `earlier_attempt_in_doubt`: a failure whose
+ * error does not {@link settlesTheId | settle the id}, and an `indeterminate` end whose
+ * error {@link AxorumError.wroteNothing | wrote nothing}. A re-pin, and an
+ * `indeterminate` end that is itself in doubt, are unchanged. Pure.
+ */
+export function afterDoubt(failure, earlier, cause) {
+    if (earlier === undefined || settlesTheId(cause)) {
+        return failure;
+    }
+    if (failure.kind === "indeterminate") {
+        if (!(cause instanceof AxorumError) || !cause.wroteNothing) {
+            return failure;
+        }
+        return {
+            kind: "indeterminate",
+            lastCause: { kind: "earlier_attempt_in_doubt", earlier, last: describeCause(failure.lastCause) },
+        };
+    }
+    return {
+        kind: "indeterminate",
+        lastCause: { kind: "earlier_attempt_in_doubt", earlier, last: describeFailure(failure, cause) },
+    };
+}
+/**
+ * Whether the call sends a submission again after `error` itself, rather than through
+ * the transport: every `503`, read with its body. The transport re-sends on the status
+ * alone and cannot tell a `503 idempotency_unseeded`, which wrote nothing, from a
+ * `503 commit_unavailable`, which may commit. Pure.
+ */
+export function redrives(error) {
+    return (error instanceof CommitUnavailableError ||
+        ((error instanceof ApiError || error instanceof UnexpectedResponseError) && error.status === 503));
+}
+/**
+ * The pause before the call sends a submission again for the `redriven + 1`th time, under
+ * {@link AUTHORIZE_RETRY_POLICY} with `draw`, or `undefined` when it would reach the
+ * deadline `remainingMs` away. Pure.
+ */
+export function redrivePause(redriven, draw, remainingMs) {
+    return pause(AUTHORIZE_RETRY_POLICY, redriven + 1, draw, remainingMs);
+}
+/**
+ * What the call ends on when the send after a re-drive pause fails with `error`: the
+ * `503` it paused after, `pausedAfter`, when the budget ran out before that send could
+ * leave (a deadline with no attempt), since the call's last answer is still that `503`;
+ * else `error`. The `503` was already heard as re-driven, so the caller lists it once.
+ * Pure.
+ */
+export function endedAfterRedrive(pausedAfter, error) {
+    return pausedAfter !== undefined && error instanceof DeadlineExceededError && error.attempts === 0
+        ? { error: pausedAfter, heard: true }
+        : { error, heard: false };
+}
+/** What one attempt that ended with `error` is listed as, or `undefined` when it has no status or connect outcome. Pure. */
+function outcomeOf(error) {
+    if (error instanceof ConnectError) {
+        return { kind: "connect" };
+    }
+    return error.status === null ? undefined : { kind: "status", status: error.status };
+}
+/**
+ * The attempt a submission's `error` ended on, as `tried` lists it: the last of a call
+ * that moved between URLs, else the one at `endpoint`; `undefined` when nothing was sent
+ * or no endpoint is known. Pure.
+ */
+export function finalAttempt(error, endpoint) {
+    if (error instanceof EndpointsExhaustedError) {
+        return error.attempts.at(-1);
+    }
+    if (!(error instanceof AxorumError) || endpoint === undefined) {
+        return undefined;
+    }
+    const outcome = outcomeOf(error);
+    return outcome === undefined ? undefined : { endpoint, outcome, rotated: false };
+}
+/**
+ * Every attempt a read of the call (the pin, the window) that failed with `error` made:
+ * those of a read that moved between URLs, else none, since no recorder hears a read.
+ * Pure.
+ */
+export function attemptsOf(error) {
+    return error instanceof EndpointsExhaustedError ? error.attempts : [];
+}
+/**
+ * The recorder of one call: hears every attempt its submissions are sent again after,
+ * from the transport (a re-sent status, by its status alone) and from the call (a `503`,
+ * its body read), and keeps them in order, and the first in doubt. Shared by every
+ * submission of the call, so doubt carries across re-pins. The Rust SDK's `Doubt`.
+ */
+export class Doubt {
+    #tried = [];
+    #earlier;
+    /** The first outcome in doubt, by its label (`"503"`, `"timeout"`), or `undefined`. */
+    get earlier() {
+        return this.#earlier;
+    }
+    /** Every attempt heard so far, in order. */
+    get tried() {
+        return [...this.#tried];
+    }
+    /** Hears an attempt the transport sent again: in doubt unless its connection never opened. */
+    resent(attempt) {
+        this.#keep(attempt, leavesDoubt(attempt.outcome));
+    }
+    /** Hears a submission the call sent again after reading its `error`: in doubt unless it wrote nothing. */
+    redriven(endpoint, error) {
+        const outcome = outcomeOf(error) ?? { kind: "status", status: 503 };
+        this.#keep({ endpoint, outcome, rotated: false }, !error.wroteNothing);
+    }
+    #keep(attempt, doubt) {
+        this.#tried.push(attempt);
+        if (doubt && this.#earlier === undefined) {
+            this.#earlier = rotationLabel(attempt.outcome);
+        }
+    }
+}
+/**
+ * Why a keyed payment must not be sent, or `undefined` to go ahead: the pure half of the
+ * key gate. A payment keyed for another agent would name that agent's transaction.
+ */
+export function keyGate(agentUri, pay) {
+    if (pay.keyedFor === undefined || pay.keyedFor === agentUri) {
+        return undefined;
+    }
+    return { kind: "keyed_for_another_agent", keyedFor: pay.keyedFor, agent: agentUri };
+}
+/**
+ * Whether a refusal from the client's kept copy of the window is read again before it
+ * stands: only a stale key, and only when the copy was kept rather than just read. The
+ * window never shrinks, so a copy that covers the key needs no second look, and one
+ * that refuses it may be out of date because the window grew.
+ */
+export function rereads(kept, gated) {
+    return kept && gated?.kind === "stale_key";
+}
+/**
+ * Whether a key may be sent at `nowMs` under the service's window, as its headers stated
+ * it (an {@link IdempotencyWindowError} when they stated none): `undefined` to send,
+ * else why not. A key minted in this process (`held` false) was never sent before and
+ * always goes ahead; one from the caller's records goes only while the window covers
+ * it. Pure; `spec/fixtures/key-gate-v1.json` pins it in both SDKs.
+ */
+export function vouch(held, key, window, nowMs) {
+    if (!held) {
+        return undefined;
+    }
+    if (window instanceof IdempotencyWindowError) {
+        return { kind: "key_window_unstated", reason: window.reason, header: window.header, value: window.value };
+    }
+    try {
+        ensureFresh(key, window, nowMs);
+    }
+    catch (error) {
+        if (error instanceof StaleIdempotencyKeyError) {
+            return {
+                kind: "stale_key",
+                reason: error.reason,
+                ageMs: error.ageMs,
+                windowSeconds: error.windowSeconds,
+                windowTicks: error.windowTicks,
+            };
+        }
+        throw error;
+    }
+    return undefined;
+}
+/**
+ * The pin loop: the only part of `authorize` that does I/O. Pins (from the shared cache,
+ * or by reading the active policy), submits, and re-pins at most
+ * {@link MAX_AUTHORIZE_PINS} times. It owns no transport retry; the client's lane holds
+ * every request to the call's deadline.
+ *
+ * @param caller - The caller's own cancellation. When it fires, its reason is thrown
+ *   as-is, never dressed up as a ledger failure.
+ */
+export async function runAuthorize(transport, agent, pay, caller) {
+    const draft = await planPayment(agent.uri, "", pay);
+    const fail = (failure, cause) => {
+        if (failure.kind === "no_active_policy") {
+            transport.pin.value = undefined;
+        }
+        throw new AuthorizeError(pay.transaction, failure, cause);
+    };
+    // Every submission of the call reports its attempts here, so doubt carries across
+    // re-pins.
+    const doubt = new Doubt();
+    const settle = (error, tried) => {
+        if (caller?.aborted === true) {
+            throw caller.reason;
+        }
+        return fail(conclude(error, pay, doubt.earlier, tried), error);
+    };
+    // Whether a key from the caller's records may leave the process now: the service's
+    // window, read once per client, must still cover it on this clock. A minted key goes
+    // ahead without a read. `undefined` to send; a failed read settles like any other.
+    // One read of the window, as `vouch` takes it; a failed read is returned as thrown.
+    const read = async () => {
+        try {
+            return { window: await transport.readWindow(caller) };
+        }
+        catch (error) {
+            return error instanceof IdempotencyWindowError ? { window: error } : { failed: error };
+        }
+    };
+    const hold = async () => {
+        // A minted key needs no read: it is never held back.
+        if (pay.origin === "minted") {
+            return undefined;
+        }
+        const kept = transport.keptWindow();
+        let window;
+        if (kept === undefined) {
+            const first = await read();
+            if ("failed" in first) {
+                return settle(first.failed, [...doubt.tried, ...attemptsOf(first.failed)]);
+            }
+            window = first.window;
+        }
+        else {
+            window = kept;
+        }
+        const gated = vouch(true, pay.idempotencyKey, window, Date.now());
+        if (!rereads(kept !== undefined, gated)) {
+            return gated;
+        }
+        // The window may have grown since the copy was taken: read it again once.
+        const again = await read();
+        if ("failed" in again) {
+            // The read failed: the kept copy's refusal stands, and nothing is sent.
+            return gated;
+        }
+        return vouch(true, pay.idempotencyKey, again.window, Date.now());
+    };
+    const refusedLocally = keyGate(agent.uri, pay);
+    if (refusedLocally !== undefined) {
+        return fail(refusedLocally, undefined);
+    }
+    const held = await hold();
+    if (held !== undefined) {
+        return fail(held, undefined);
+    }
+    let pinned = transport.pin.value;
+    if (pinned === undefined) {
+        let active;
+        try {
+            active = await transport.activePolicy(caller);
+        }
+        catch (error) {
+            return settle(error, attemptsOf(error));
+        }
+        if (active === null) {
+            return fail({ kind: "no_active_policy" }, undefined);
+        }
+        transport.pin.value = active;
+        pinned = active;
+    }
+    for (let pins = 1;; pins += 1) {
+        // A re-pinned send is held to the window again: the key has aged since the first,
+        // and the window read is the client's kept one.
+        if (pins > 1) {
+            const regated = await hold();
+            if (regated !== undefined) {
+                return fail(afterDoubt(regated, doubt.earlier), undefined);
+            }
+        }
+        const token = await agent.attestation(pay.transaction);
+        // The deadline is taken from one wall-clock read and held on the monotonic clock.
+        const expMs = attestationExpiryMs(token);
+        if (typeof expMs === "string") {
+            return fail({ kind: "attestation_unavailable" }, new InvalidAgentError(expMs));
+        }
+        const deadline = submissionDeadline(expMs, Date.now(), performance.now());
+        if (deadline === undefined) {
+            return fail({ kind: "attestation_expiring", expiresAt: formatUtcMs(expMs) }, undefined);
+        }
+        // The plan carries the payment key's mint time, so the pin stamps it.
+        const envelope = pinIntent({ ...draft, attestation: token }, pinned);
+        let outcome;
+        let ended;
+        try {
+            outcome = await transport.submit(envelope, caller, {
+                deadline,
+                onResend: (attempt) => doubt.resent(attempt),
+                onRedrive: (endpoint, error) => doubt.redriven(endpoint, error),
+                onEnded: (endpoint) => {
+                    ended = endpoint;
+                },
+            });
+        }
+        catch (error) {
+            const disposition = error instanceof StalePolicyError ? classify(error, pay) : undefined;
+            if (disposition?.action !== "repin" || pins >= MAX_AUTHORIZE_PINS) {
+                const last = finalAttempt(error, ended);
+                return settle(error, last === undefined ? doubt.tried : [...doubt.tried, last]);
+            }
+            transport.pin.value = disposition.active;
+            pinned = disposition.active;
+            continue;
+        }
+        const answer = judge(outcome);
+        if (answer === undefined) {
+            throw new AuthorizeError(pay.transaction, { kind: "unexpected_verdict", outcome });
+        }
+        return answer;
+    }
+}
+//# sourceMappingURL=authorize.js.map