@passflow/core 0.20.0 → 0.20.1

package/dist/lib/upgrade/core.d.ts

@@ -1,353 +0,0 @@
-/**
- * The upgrade core: ONE implementation, transport-agnostic by construction.
- *
- * Every behaviour lives here — recognise a challenge on both channels, decide
- * whether the URL is in scope, run or join the elevation, replay once behind the
- * re-entry guard, and decide the outcome. The four surfaces the SDK offers
- * (`withAuth`, `attachAuth`, `createClient` and the internal axios seam) are
- * ADAPTERS over this function, and the prohibition on them is absolute:
- *
- *   **NO LOGIC IN AN ADAPTER.**
- *
- * An adapter translates transport shapes in and out and does nothing else. It
- * may not parse a challenge, compare a bar, decide scope, count a retry, choose
- * an error class or read a body. If an adapter would need a decision, the
- * decision belongs here instead. The reason is not elegance: an axios response
- * interceptor receives an `AxiosError`, not a callable `next`, and re-issues
- * through `instance.request(config)` — so four independent wirings with two
- * outcome vocabularies is what happens by default, and it is the largest
- * quantity of parallel behaviour in this feature. A row that passes on one
- * adapter and fails on another is a leak of logic out of this file, and the fix
- * is to move it back in, never to fork the expectation per surface.
- *
- * `CoreOutcome` is the settlement table as a discriminated union, which is what
- * makes that table the adapters' specification rather than a prose parallel.
- */
-import { type AssuranceBar, type ChallengeChannel, type UpgradeChallenge, type UpgradeDiagnosticSink } from './challenge';
-import { type UpgradeElevation, type Waiter } from './controller';
-import type { ReplayHints, ReplayPolicy } from './replay';
-import type { RequestSnapshot } from './snapshot';
-/**
- * Where the SDK is allowed to act on a challenge.
- *
- * Two domains, each with its own rule, and NO derived default. Deriving the set
- * was the category error the previous model made: same-origin by default, the
- * document origin, "the origin the first 401 came from" — every one of those is
- * the SDK inferring a trust boundary it has no information about, and a
- * fabricated 403 body from an observed endpoint can provoke a genuine elevation
- * whose replay then carries the freshly elevated credential to that endpoint.
- *
- * The resolved scope is passed IN. No adapter and no wrapper derives it.
- */
-export type InterceptionScope = {
-    /**
-     * Domain 1 — Passflow's own API, derived from `PassflowConfig.url`. Always in
-     * scope on any surface the SDK is attached to, which is what makes the
-     * zero-config half of the design work. `null` when no `url` is configured:
-     * domain 1 is then EMPTY and nothing throws, but the first parseable challenge
-     * raises a diagnostic naming `url`, because an app with no `url` would
-     * otherwise silently drop `/auth/session/exchange`'s own 403.
-     */
-    passflow: {
-        origin: string;
-        pathPrefix?: string;
-    } | null;
-    /**
-     * Domain 2 — the customer's own backend, exactly as declared. An absolute
-     * origin (optionally with a path prefix) or a same-origin path prefix
-     * (`'/api'`). `[]` means nothing beyond domain 1 is in scope — and the
-     * predicate must NOT early-return on it.
-     */
-    backend: string[];
-};
-export type UpgradeInterceptorOptions = {
-    /**
-     * Starts or joins the single flight, registering this waiter.
-     *
-     * Typed to accept a `void`-returning host as well, so a caller that does not
-     * use the controller's waiter bookkeeping still works — it just forfeits the
-     * per-waiter outcome summary, and the core then trusts the server's verdict on
-     * the replay for the `insufficient` decision, which it does anyway.
-     */
-    elevate: (challenge: UpgradeChallenge, waiter: Waiter) => Promise<UpgradeElevation | void>;
-    /** REQUIRED. Resolved once, where the client is built. */
-    scope: InterceptionScope;
-    /** `'header'` requires the standards channel and never reads the body. */
-    requireChallengeChannel?: 'header';
-    /**
-     * NARROWING ONLY. Returning `false` excludes a URL the two domains admitted;
-     * returning `true` can never widen, so an always-true predicate cannot
-     * restore the allow-all default this design abolished.
-     *
-     * It is given the snapshot's **normalised absolute `href`**, never the raw
-     * string the caller passed: a narrowing decision is an authorization decision,
-     * and those are made on the URL the platform will actually send to (§13.4
-     * revision 6). A predicate written against relative paths must therefore
-     * match on the path of an absolute URL — `new URL(url).pathname` — rather than
-     * on `startsWith('/…')`.
-     */
-    shouldIntercept?: (url: string) => boolean;
-    replay?: ReplayPolicy;
-    /** Default `'resolve-original'`. The fetch adapter's only option. */
-    onCancel?: 'resolve-original' | 'reject';
-    /** §5.5. Snapshotted before the elevation and read again after it. */
-    authorizationSwap?: () => {
-        from: string;
-        to: string;
-    } | undefined;
-    /** Default sink is `console.warn`; pass a function to route elsewhere. */
-    onUpgradeDiagnostic?: UpgradeDiagnosticSink;
-    /** The bar the elevation reached, when the host can read it from the new token. */
-    readObtainedBar?: () => AssuranceBar | undefined;
-};
-/**
- * How an adapter is given its options: a value, or a getter read per challenge.
- *
- * The getter form is the one the facade uses, and the reason is a defect this
- * seam actually had. `enable()` resolves the interception policy — the scope in
- * particular — and an adapter handed the RESULT of that resolution freezes it at
- * attach time: a client built at module scope, or in a child's `useMemo`, is
- * attached before the provider's enable effect runs, so it would hold
- * `backend: []` forever and never intercept the customer's own backend. A
- * getter also makes re-enabling with a NARROWER `backend` take effect on
- * clients that were already attached, instead of leaving them on the wider
- * scope.
- *
- * A plain value is still accepted: a caller wiring the adapters directly, with
- * a scope it resolved itself, has nothing to re-read.
- */
-export type UpgradeInterceptorOptionsSource = UpgradeInterceptorOptions | (() => UpgradeInterceptorOptions);
-/** Resolves an options source. Call it ONCE per challenge, never per module. */
-export declare const resolveInterceptorOptions: (source: UpgradeInterceptorOptionsSource) => UpgradeInterceptorOptions;
-/**
- * What the core is given about one challenged request, and what it can do with
- * it. The adapter builds this and nothing more.
- */
-/**
- * A live view of one caller's abort state, with optional subscription.
- *
- * `AbortSignal` satisfies this structurally, and so does the minimal
- * `{ get aborted() }` getter object the adapters build. The listener pair is
- * what makes the abort an EVENT rather than a flag polled after the fact.
- */
-export type AbortView = {
-    aborted: boolean;
-    reason?: unknown;
-    addEventListener?(type: 'abort', listener: () => void): void;
-    removeEventListener?(type: 'abort', listener: () => void): void;
-};
-export type ChallengeContext = {
-    status: number;
-    /** The shipped callback shape, which is why one parser serves both surfaces. */
-    getHeader(name: string): string | null | undefined;
-    /**
-     * Reads the body. MUST be safe to call only in scope, and MUST NOT disturb the
-     * original payload — on the fetch surface that means `res.clone().json()`, so
-     * the response the caller receives still has `bodyUsed === false`. The core
-     * calls it only when the scope and the channel policy both permit.
-     */
-    readBody(): Promise<unknown>;
-    /**
-     * The normalised, immutable snapshot of the request that was challenged —
-     * §13.4 revision 6's invariant, and the ONLY description of the request this
-     * function will look at.
-     *
-     * The adapter takes it once, before dispatch, and hands the same object to
-     * the scope check, this context, the diagnostics and `planReplay`. Nothing
-     * here re-reads the caller's `Request`, `RequestInit` or axios config, so a
-     * mutation while the prompt is open cannot change what was authorized, what
-     * was reported or what is replayed.
-     */
-    request: RequestSnapshot;
-    /**
-     * Replays the ORIGINAL request, once, with the elevated credential. The
-     * adapter supplies it; the core decides whether and when it is called, and
-     * marks it replayed.
-     */
-    replay(hints?: ReplayHints): Promise<ChallengeContext>;
-    /** Where the adapter stores the core's per-request markers. */
-    markers: {
-        upgradeTransaction?: true;
-        replayed?: true;
-    };
-    /**
-     * The adapter's native payload — a `Response`, an `AxiosResponse`, an
-     * `AxiosError`. The core never inspects it; it only hands it back so the
-     * adapter can return the real thing.
-     */
-    raw?: unknown;
-    /** `false` when `planReplay` refused. The prompt is then never opened. */
-    replayable?: boolean;
-    /** Why the replay is unsupported, for the diagnostic. */
-    replayUnsupportedReason?: string;
-    /**
-     * The caller's abort state. The SDK never aborts it.
-     *
-     * Read as a LIVE view, never a snapshot, because the core reads it after
-     * awaiting the elevation. The two listener methods are optional and carry
-     * REQ-C12: with them the core races the abort against the pending proof, so
-     * the caller's own promise settles at abort time instead of waiting for a
-     * prompt it has walked away from; without them (a bare `{ aborted }` view)
-     * the core falls back to reading the flag once the elevation settles. The
-     * elevation itself is never cancelled either way — it is shared.
-     */
-    signal?: AbortView;
-    /** `'cors'` distinguishes the one actionable `'no-channel'` variant. */
-    responseType?: string;
-    /**
-     * `true` when the adapter received this exchange as a REJECTION rather than
-     * as a response — axios' `validateStatus` contract, where every non-2xx
-     * rejects. `fetch` resolves a 401, so its adapter never sets it.
-     *
-     * The core classifies the exchange identically either way: this flag decides
-     * only how a `replayed` outcome is handed back, so a replay that failed on
-     * its own terms keeps failing on the surface's own convention instead of
-     * being resolved as a value.
-     */
-    rejected?: boolean;
-};
-/**
- * Every terminal outcome, as the settlement table defines them.
- *
- * The invariant: **every path settles.** There is no input that produces a
- * pending promise.
- */
-export type CoreOutcome = 
-/** Not a challenge. Pass the response through untouched. */
-{
-    kind: 'not-a-challenge';
-}
-/** A challenge the SDK is not allowed to act on. Diagnostic only; no body was read. */
- | {
-    kind: 'out-of-scope';
-} | {
-    kind: 'replayed';
-    response: ChallengeContext;
-}
-/**
- * The proof completed and the operation's replay was challenged again.
- *
- * `response` is the SECOND challenge response, which the fetch surface
- * resolves and tags (§13.3) — so the decision "which response does the caller
- * receive" stays here rather than becoming a per-adapter `??` chain. It is
- * absent only on the re-entry path, where the adapter already holds the object
- * it was handed.
- */
- | {
-    kind: 'insufficient';
-    obtained: AssuranceBar;
-    required: AssuranceBar;
-    response?: ChallengeContext;
-} | {
-    kind: 'cancelled';
-} | {
-    kind: 'exhausted';
-    error: Error;
-} | {
-    kind: 'unsatisfiable';
-} | {
-    kind: 'unavailable';
-} | {
-    kind: 'session-changed';
-} | {
-    kind: 'transport-failure';
-    status?: number;
-    retryable: boolean;
-    error: Error;
-} | {
-    kind: 'replay-unsupported';
-} | {
-    kind: 'aborted';
-    reason: unknown;
-};
-/**
- * The scope decision, identical for every surface, and made on the SNAPSHOT.
- *
- * Precedence, in one ordered rule: domain 1, then domain 2, then
- * `shouldIntercept` as a narrowing-only hook. There is no allow-all opt-in — a
- * developer who genuinely wants every origin lists every origin, which is a
- * sentence they can read in a diff.
- *
- * It takes a `RequestSnapshot` and not a string by design (§13.4 revision 6): a
- * string parameter is an invitation to decide authorization on an un-normalised
- * value, which is exactly the defect this signature removes.
- */
-export declare const isInterceptionScope: (request: RequestSnapshot, scope: InterceptionScope, shouldIntercept?: (url: string) => boolean) => boolean;
-/**
- * Detect → scope → elevate → replay once → classify. The one implementation.
- *
- * "Retry exactly once" is structural rather than counted: there is no path from
- * the replay back to the elevation. On a surface that re-enters this function
- * with the replayed request — axios does, because the replay goes back through
- * `instance.request(config)` and hits the same response interceptor — the replay
- * marker is read first and the response is classified without elevating. That
- * guard is written here, once; the adapter only supplies the marker's storage.
- */
-export declare const handleChallenge: (ctx: ChallengeContext, options: UpgradeInterceptorOptions) => Promise<CoreOutcome>;
-/**
- * The error class a non-fetch surface rejects with, or `undefined` when the
- * outcome is not a rejection.
- *
- * axios' own contract, expressed in `validateStatus`, is that a non-2xx response
- * REJECTS. Resolving a declined step-up there would invert the library's
- * contract: every caller's post-`await` success path would run after the user
- * clicked "Not now", and `await api.post('/transfer')` would resolve with only a
- * status check the customer was never instructed to write standing between that
- * and treating an unperformed elevated action as performed.
- *
- * Every class carries a literal `code` discriminant as well as being
- * `instanceof`-checkable, and the `code` is the testable tag: it survives
- * bundling, duplicate package copies and cross-realm boundaries.
- */
-export declare const coreOutcomeToError: (outcome: CoreOutcome) => Error | undefined;
-/**
- * What an adapter must do with an outcome: hand back an object, or throw.
- *
- * Both surfaces settle from this, so §13.3's table has exactly one encoding in
- * the codebase. An adapter that reached its own conclusion about which response
- * a caller receives, or which error class, would be the per-surface drift the
- * single core exists to prevent.
- */
-export type Settlement<T> = {
-    settle: 'resolve';
-    value: T;
-} | {
-    settle: 'reject';
-    error: unknown;
-};
-/**
- * The fetch surface's settlement.
- *
- * `fetch` resolves on 401 and every caller is written as `if (!res.ok)`, so a
- * declined step-up comes back as the original response — tagged, so it is
- * discriminable — rather than as a rejection their code has never handled. The
- * two exceptions are an abort (which throws the signal's reason, as `fetch`
- * itself does) and the explicit `onCancel: 'reject'` opt-out.
- */
-export declare const settleFetchOutcome: <T extends object>(outcome: CoreOutcome, original: T, options: UpgradeInterceptorOptions) => Settlement<T>;
-/**
- * The axios surface's settlement.
- *
- * axios' own contract, expressed in `validateStatus`, is that a non-2xx
- * response rejects, so every non-success outcome rejects here — with the tagged
- * error class for a step-up outcome, and with the transport's own error when
- * the SDK did not act.
- */
-export declare const settleAxiosOutcome: <T>(outcome: CoreOutcome, originalError: unknown) => Settlement<T>;
-/**
- * Tags the response an adapter is about to resolve with the outcome that
- * produced it. The mapping is here, not in the adapter: choosing which set a
- * `CoreOutcome` belongs to is a decision.
- */
-export declare const tagUpgradeOutcome: <T extends object>(response: T, outcome: CoreOutcome) => T;
-/** "You were challenged and you declined" — as opposed to "you were not authorised". */
-export declare const isUpgradeCancelled: (response: object) => boolean;
-export declare const isUpgradeExhausted: (response: object) => boolean;
-export declare const isUpgradeInsufficient: (response: object) => boolean;
-export declare const isUpgradeUnsatisfiable: (response: object) => boolean;
-export declare const isUpgradeUnavailable: (response: object) => boolean;
-export declare const isUpgradeSessionChanged: (response: object) => boolean;
-/** FR1's non-retryable 400 class. */
-export declare const isUpgradeTransportFailure: (response: object) => boolean;
-export type { ChallengeChannel };
-//# sourceMappingURL=core.d.ts.map

package/dist/lib/upgrade/core.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../lib/upgrade/core.ts"],"names":[],"mappings":"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"}

package/dist/lib/upgrade/errors.d.ts

@@ -1,208 +0,0 @@
-/**
- * Upgrade transport error classification.
- *
- * The server speaks two languages about the same failure: an exact
- * `PassflowError.id` and an HTTP status. The id is read FIRST and the status only
- * as a fallback, because the id names the cause while the status is a bucket —
- * `refreshErrorStatus` maps four unrelated upgrade errors onto one bare 401, and
- * three of them want the prompt kept open while the fourth ends the elevation.
- *
- * This module is pure: it imports nothing and touches no transport. It
- * duck-types whatever it is handed — a `PassflowError`, a raw `AxiosError`, or a
- * bare object — so it can be tested with literals and reused from any surface.
- */
-/** What kind of failure the server reported, in remedy terms rather than status terms. */
-export type UpgradeErrorKind = 
-/** The user typed the wrong code. Retry with a FRESH prepare round; the modal stays open. */
-'wrong_code'
-/** Bad, expired, spent or foreign challenge. Same remedy as `wrong_code`. */
- | 'challenge_spent'
-/** The server's per-challenge attempt budget is burned. Stop; a fresh prepare will not help. */
- | 'exhausted'
-/**
- * The CONTROLLER's local attempt budget is burned: the user has answered
- * wrongly `maxAttempts` times and the elevation gives up.
- *
- * Terminal, and distinct from the four retryable kinds for one specific
- * reason: the loop's last failure is usually a `wrong_code`, which IS
- * retryable, and returning that error as the flight's outcome told every
- * surface above "ask them again" for a flight that will never ask again — so
- * the UI re-prompted forever against a budget the server had already closed.
- * The budget being spent is the fact that must travel, not the last answer
- * that spent it; the answer travels on `cause`.
- */
- | 'attempts_exhausted'
-/** This FACTOR is not enrolled for this user. Drop it for this flight, offer the others. */
- | 'not_registered'
-/** Our static `requiresPrepare` disagrees with the server. Recover by asserting directly. */
- | 'prepare_not_required'
-/** Unsupported factor, or no session at all. Not retryable; surface it, do not log the user out. */
- | 'fatal'
-/** The deployment cannot serve an upgrade at all (no challenge storage, or a BFF commit). */
- | 'unavailable'
-/** A malformed response from a server that claimed success. */
- | 'protocol'
-/** No response: the request never completed. */
- | 'network'
-/**
- * A genuine session failure DURING the elevation — a commit 401 that is none of
- * the four recoverable upgrade errors, so it is an expired or revoked refresh
- * token rather than a bad answer. Terminates the elevation instead of
- * re-prompting, and the transport invalidates the session itself.
- */
- | 'session_changed';
-/** Server error ids this module classifies. Verified against `src/l/messages_const.go`. */
-export declare const UpgradeErrorIds: {
-    readonly twoFactorCodeInvalid: 'error.api.request.2fa_code.invalid';
-    readonly challengeInvalid: 'error.upgrade.challenge_invalid';
-    readonly challengeSessionMismatch: 'error.upgrade.challenge_session_mismatch';
-    readonly challengeTooManyAttempts: 'error.upgrade.challenge_too_many_attempts';
-    readonly unsupportedFactor: 'error.upgrade.unsupported_factor';
-    readonly noSession: 'error.upgrade.no_session';
-    readonly unavailable: 'error.upgrade.unavailable';
-    readonly methodNotRegistered: 'error.upgrade.method_not_registered';
-    readonly prepareNotRequired: 'error.upgrade.prepare_not_required';
-    readonly methodNotSupported: 'error.2fa.method_not_supported';
-    readonly twoFactorNotEnabled: 'error.2fa.not_enabled';
-    readonly notImplemented: 'error.not.implemented';
-    readonly tokenInvalid: 'error.api.request.token.invalid';
-};
-/**
- * **Every** error `refreshErrorStatus` maps to a 401 on the commit path, as
- * enumerated by `src/web/api/refresh_token.go:157-178`.
- *
- * All five are "recoverable" in the session sense: every one of them is the
- * upgrade protocol talking, so none of them means the session died. Note that
- * `challenge_too_many_attempts` is in here yet is NOT retryable — it ends the
- * elevation while leaving the session intact. The two axes are independent and
- * are deliberately not collapsed.
- *
- * `error.2fa.not_enabled` was missing from this list, which signed out a user
- * who had no 2FA enrolled the moment an elevation reached the commit round —
- * the exact lock-out PFL-497 exists to prevent. The set is kept complete for
- * documentation and for callers, but the invalidation decision no longer rests
- * on it: see `invalidatesSessionOnCommit`, which is the inverse predicate.
- */
-export declare const RECOVERABLE_COMMIT_ERROR_IDS: readonly string[];
-/**
- * Error ids that positively mean the SESSION is gone, not merely the elevation.
- *
- * This is the predicate the transport invalidates on, and it is deliberately a
- * POSITIVE list rather than the complement of the recoverable one. The server's
- * 401 set on the commit path is enumerated and small, so a list of "ids that
- * mean the session died" can be complete in a way that "everything else" never
- * is; and when a future server adds a sixth 401 id, an allow-list of expiries
- * fails toward "I don't know" rather than toward "log them out", which is this
- * feature's governing rule. A client-side miss costs a stale session that the
- * next ordinary 401 clears; a false positive costs the user their session in
- * the middle of proving who they are.
- */
-export declare const SESSION_INVALIDATING_COMMIT_ERROR_IDS: readonly string[];
-/** True when a kind leaves the elevation alive. Single source for `retryable`. */
-export declare const isRetryableUpgradeKind: (kind: UpgradeErrorKind) => boolean;
-export type UpgradeTransportErrorInit = {
-    kind: UpgradeErrorKind;
-    message?: string;
-    status?: number;
-    /** The `PassflowError.id`, verbatim, when the server supplied one. */
-    errorId?: string;
-    cause?: unknown;
-};
-/** Which round of the transaction failed. The same status means different things on each. */
-export type UpgradeEndpoint = 'start' | 'refresh';
-/**
- * A classified transport failure.
- *
- * `code` is the literal, bundling-proof discriminant every upgrade error class
- * carries; the server's own id lives in `errorId`. (The design's §3.3 called the
- * latter `code`, which §13.3 then claimed for the literal tag — `errorId` keeps
- * both without one shadowing the other.)
- */
-export declare class UpgradeTransportError extends Error {
-    readonly name = "UpgradeTransportError";
-    readonly code: 'upgrade_transport';
-    readonly kind: UpgradeErrorKind;
-    readonly status?: number;
-    readonly errorId?: string;
-    readonly retryable: boolean;
-    /** Declared here rather than inherited: `Error.cause` is ES2022 and this build targets ES2021 libs. */
-    readonly cause?: unknown;
-    constructor(init: UpgradeTransportErrorInit);
-}
-/**
- * Reports whether a value is one of the SDK's own upgrade error classes — an
- * outcome that has already been decided, on any surface.
- *
- * Used where a lower layer must not re-bucket a settled outcome: classifying an
- * `UpgradeSessionChangedError` as a bare network failure (which is what
- * happened, because it carries no `response`) turned §13.3's `session changed
- * mid-flight` row into `upgrade_transport` on all four adapters.
- */
-export declare const isUpgradeSdkError: (e: unknown) => e is Error & {
-    code: string;
-};
-/** Reports whether a value is an already-classified transport failure. */
-export declare const isUpgradeTransportError: (e: unknown) => e is UpgradeTransportError;
-/**
- * Classifies a rejection from either upgrade round into an `UpgradeTransportError`.
- *
- * Already-classified errors pass through unchanged, so a nested call cannot
- * re-bucket a `prepare_not_required` into something terminal.
- */
-export declare const classifyUpgradeError: (e: unknown, endpoint: UpgradeEndpoint) => UpgradeTransportError;
-/**
- * Reports whether a classified commit failure is a KNOWN upgrade-protocol error
- * that leaves the session intact.
- *
- * Informational: it answers "is this one of the server's enumerated commit
- * 401s". It is NOT the invalidation decision — `invalidatesSessionOnCommit` is,
- * and an unrecognised id is not an expiry just because this list has not heard
- * of it.
- */
-export declare const isRecoverableCommitFailure: (error: UpgradeTransportError) => boolean;
-/**
- * Reports whether a classified commit failure means the SESSION has ended.
- *
- * The one predicate the transport invalidates on, and the inverse of what this
- * module used to ask. `undefined` — no id at all — is explicitly NOT an expiry:
- * a 401 the SDK cannot explain is "I don't know", and "I don't know" must never
- * resolve to signing the user out mid-verification.
- */
-export declare const invalidatesSessionOnCommit: (error: UpgradeTransportError) => boolean;
-/** The bar a challenge demanded, or an elevation reached, on both axes. */
-export type AssuranceBar = {
-    /** The raw winning `acr_values` list, for display and diagnostics. */
-    acrValues?: string;
-    /** The parsed bar. `undefined` = unknown, or not constrained on this axis. */
-    level?: number;
-    /** The freshness constraint, when that is what was demanded. */
-    maxAge?: number;
-};
-/**
- * The elevation completed, and the protected operation's replay was challenged
- * again: the proof was real but did not reach this operation's bar.
- *
- * This is the outcome that makes the AAL3-with-only-TOTP path honest. It is
- * per-operation, never per-proof — a requestless `passflow.upgrade()` with no
- * stated bar can never produce it, because it has nothing to replay.
- */
-export declare class UpgradeInsufficientError extends Error {
-    readonly name = "UpgradeInsufficientError";
-    readonly code: 'upgrade_insufficient';
-    readonly obtained: AssuranceBar;
-    readonly required: AssuranceBar;
-    constructor(obtained: AssuranceBar, required: AssuranceBar, message?: string);
-}
-/** The deployment cannot serve an upgrade at all — no challenge storage, or a BFF commit. */
-export declare class UpgradeUnavailableError extends Error {
-    readonly name = "UpgradeUnavailableError";
-    readonly code: 'upgrade_unavailable';
-    constructor(message?: string);
-}
-/** The session ended or changed while the elevation was running (§7.4). */
-export declare class UpgradeSessionChangedError extends Error {
-    readonly name = "UpgradeSessionChangedError";
-    readonly code: 'upgrade_session_changed';
-    constructor(message?: string);
-}
-//# sourceMappingURL=errors.d.ts.map

package/dist/lib/upgrade/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../lib/upgrade/errors.ts"],"names":[],"mappings":"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"}