@passflow/core 0.14.1 → 0.16.0

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

@@ -0,0 +1,196 @@
+/**
+ * The request snapshot: ONE normalised, immutable description of the request
+ * that carried a challenge, captured before dispatch.
+ *
+ * ## Why this module exists
+ *
+ * Every authorization decision the upgrade feature makes — is this URL in scope,
+ * what does the diagnostic name, what does the replay re-send — must be made on
+ * the SAME description of the request, and that description must be the one the
+ * platform will actually act on. Three defects in this feature were the same
+ * defect from three angles:
+ *
+ *   1. the scope check hand-parsed the caller's URL *string*, while the browser
+ *      normalises it before dispatch;
+ *   2. the challenge context re-read the caller's live `input` at challenge
+ *      time, while the replay was pinned to the plan-time URL and body;
+ *   3. the replay could re-send a different header set than the one that was
+ *      examined.
+ *
+ * So the request is normalised and frozen ONCE, here, and the snapshot is the
+ * only thing the scope check, the challenge context, the diagnostics and the
+ * replay are given. Nothing downstream holds a live reference to the caller's
+ * `Request`, `RequestInit` or axios config.
+ *
+ * ## The normalisation rule, and why it is the platform's own parser
+ *
+ * **Resolve with `new URL(raw, base)` and compare `origin` on the result.**
+ *
+ * WHATWG URL parsing is not a string scan. For a special scheme it converts
+ * backslashes to forward slashes and strips ASCII tab (0x09), LF (0x0A) and CR
+ * (0x0D) *before* parsing. A scope check that inspects the raw string therefore
+ * sees a same-origin relative path where the browser resolves a foreign origin:
+ * `'/\\evil.example/x'`, `'/\t/evil.example/x'` and `'\\\\evil.example/x'` all
+ * resolve to `https://evil.example` (§13.4's SF-3, SF-4, SF-7). Each one would
+ * attach a step-up-elevated credential to a request leaving for an
+ * attacker-controlled host.
+ *
+ * **The percent-encoded forms are the mirror image, and they are POSITIVES.**
+ * `'/%5Cevil.example/x'`, `'/%09/evil.example/x'` and `'/%2F%2Fevil.example/x'`
+ * all resolve to the page's OWN origin and must stay in scope (SF-9..SF-12):
+ * the parser decodes nothing that could change the authority, so `%5C` is not a
+ * backslash, `%09` stays an ordinary path character and `%2F%2F` does not begin
+ * an authority. They are legitimate same-origin requests with odd-looking paths.
+ *
+ * That asymmetry is the entire argument for resolving rather than filtering. A
+ * list of rejected characters is a denylist against a parser, and the parser is
+ * the authority: it is bypassed by the raw forms, whose bytes it rewrites before
+ * it parses them, AND it is wrong in the opposite direction on the encoded
+ * forms, which it refuses as hostile when the platform treats them as plain
+ * path text. Resolving first gets both directions — and the vectors nobody has
+ * thought of yet — for free.
+ *
+ * The operative consequence for anyone editing this file: hand the input to
+ * `new URL` **undecoded and un-normalised**. Any decoding, trimming or
+ * rewriting before that call reintroduces one half of the defect or the other.
+ *
+ * Off the browser there is no document, so there is no "same origin" to resolve
+ * against. A relative URL is then resolved against a RESERVED sentinel origin
+ * (`.invalid` is reserved by RFC 2606 and can never be a real host), which keeps
+ * exactly one code path: a URL that resolves to the sentinel's origin is a
+ * genuinely relative one, and anything that steers the authority elsewhere —
+ * `//evil.example/x` included — resolves away from it and is no longer relative.
+ * The sentinel is `https:` precisely because it must be a SPECIAL scheme: the
+ * backslash and tab rules above apply only to special schemes, so a custom
+ * scheme would be a different parser and would miss the vectors.
+ */
+import type { BodyKind } from './replay';
+/** One captured header. Lower-cased name, value verbatim. */
+export type SnapshotHeader = readonly [name: string, value: string];
+/**
+ * The frozen description of one request.
+ *
+ * Immutable by construction: `Object.freeze` on the snapshot and on its header
+ * list, and the body already captured by value where the shape is mutable. It
+ * carries no live reference to anything the caller can still change.
+ */
+export type RequestSnapshot = {
+    /** Exactly what the caller passed, for diagnostics only. NEVER for a decision. */
+    readonly raw: string;
+    /**
+     * The absolute, platform-normalised URL the request will actually be sent to,
+     * or `raw` when it could not be resolved at all (a malformed URL).
+     *
+     * This is the value every decision and the replay use.
+     */
+    readonly href: string;
+    /**
+     * The URL to actually DISPATCH a replay to.
+     *
+     * Identical to `href` wherever a real base existed — a browser, or any host
+     * that resolved the URL absolutely — which is the case every decision cares
+     * about. It falls back to `raw` only when resolution used the reserved
+     * sentinel base, i.e. a relative URL on a host with no document: the
+     * sentinel's origin is a reserved name that resolves to nothing, so sending
+     * `href` there would send the request into a hole. The transport's own base
+     * (axios' `baseURL`, the runtime's fetch base) then resolves the captured
+     * string, exactly as it did for the original send.
+     *
+     * It is still a captured STRING, never the caller's object, so the TOCTOU
+     * this module exists to close stays closed on that path too.
+     */
+    readonly dispatchUrl: string;
+    /** The resolved origin, or `undefined` when the URL could not be resolved. */
+    readonly origin?: string;
+    /** The resolved pathname, or the raw path when the URL could not be resolved. */
+    readonly pathname: string;
+    /** False when the URL could not be parsed even against the base. */
+    readonly resolved: boolean;
+    /**
+     * True when the resolved origin is the base's own — the page's origin on a
+     * browser, the sentinel's off it, which means "genuinely relative".
+     *
+     * This is what a same-origin path-prefix pattern (`backend: '/api'`) tests,
+     * and it is the one bit that makes `'/\\evil.example/x'` fail where `'/api/x'`
+     * passes.
+     */
+    readonly relativeToBase: boolean;
+    /** Upper-cased, with the same precedence the transport itself applies. */
+    readonly method: string;
+    /** The effective header set, captured once. Frozen. */
+    readonly headers: readonly SnapshotHeader[];
+    /** How the body can be re-sent, which is what decides replayability. */
+    readonly bodyKind: BodyKind;
+    /**
+     * The already-captured body. `undefined` means "the caller passed no body
+     * key", which is distinct from an explicit `null`.
+     */
+    readonly body?: unknown;
+};
+/**
+ * The reserved origin a relative URL is resolved against when there is no
+ * document. RFC 2606 reserves `.invalid`, so no real deployment can collide
+ * with it, and `https:` keeps the parser on its special-scheme rules.
+ */
+export declare const RELATIVE_BASE = "https://passflow-relative.invalid";
+/** What a URL normalised to. Pure: it takes the base, it does not read one. */
+export type NormalisedUrl = {
+    href: string;
+    origin?: string;
+    pathname: string;
+    resolved: boolean;
+    relativeToBase: boolean;
+    /** True when no real base existed and the reserved sentinel was used. */
+    sentinelBase: boolean;
+};
+/**
+ * Resolves one URL with the platform's own parser.
+ *
+ * `base` defaults to the document base (or the sentinel off the browser). The
+ * ONLY comparison any caller may make afterwards is on `origin` — never on the
+ * raw string.
+ */
+export declare const normaliseUrl: (raw: string, base?: string) => NormalisedUrl;
+/**
+ * Captures a header bag by value.
+ *
+ * Every shape the two transports produce arrives here: a DOM `Headers`, an
+ * `AxiosHeaders`, a plain object, an entry array, or an array-valued node bag.
+ * Copying is the point — the caller may still hold and mutate the original.
+ */
+export declare const captureHeaders: (headers: unknown) => readonly SnapshotHeader[];
+/** Reads a captured header. Case is already normalised, so this is exact. */
+export declare const snapshotHeader: (snapshot: RequestSnapshot, name: string) => string | undefined;
+/** What a caller must supply to take a snapshot. Everything else is derived. */
+export type RequestSnapshotInit = {
+    url: string;
+    method?: string;
+    headers?: unknown;
+    bodyKind: BodyKind;
+    /** Pass the key only when the caller supplied a body, so `undefined` stays meaningful. */
+    body?: unknown;
+    /** Overrides the document base. Tests and non-browser hosts only. */
+    base?: string;
+};
+/**
+ * Takes the snapshot. Call it ONCE per request, BEFORE dispatch.
+ *
+ * Frozen on the way out: a snapshot that could be edited after the scope
+ * decision would reintroduce the very TOCTOU this module removes.
+ */
+export declare const createRequestSnapshot: (init: RequestSnapshotInit) => RequestSnapshot;
+/**
+ * Applies the §5.5 credential swap to a captured header set, by EXACT match.
+ *
+ * Equality with the token we hold is what proves the header was ours; any other
+ * value is forwarded untouched, because rewriting a header we do not own would
+ * be a security bug. Returns the same frozen array when nothing changed, so the
+ * common path allocates nothing.
+ */
+export declare const swapAuthorization: (headers: readonly SnapshotHeader[], swap?: {
+    from: string;
+    to: string;
+}) => readonly SnapshotHeader[];
+/** The captured headers as the plain object both transports accept. */
+export declare const headersToObject: (headers: readonly SnapshotHeader[]) => Record<string, string>;
+//# sourceMappingURL=snapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../../lib/upgrade/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,sCAAsC,CAAC;AAuBjE,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,EAAE,OAAM,MAAyB,KAAG,aAgC3E,CAAC;AAMF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,OAAO,KAAG,SAAS,cAAc,EA4CxE,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,SAQjF,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,mBAAmB,KAAG,eAkBjE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAC5B,SAAS,SAAS,cAAc,EAAE,EAClC,OAAO;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,KAClC,SAAS,cAAc,EAazB,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,eAAe,GAAI,SAAS,SAAS,cAAc,EAAE,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAMzF,CAAC"}

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

@@ -0,0 +1,69 @@
+/**
+ * The HTTP adapter behind the `UpgradeTransport` port.
+ *
+ * It owns no axios instance. Both rounds arrive as narrow, function-shaped
+ * dependencies, which keeps HTTP vocabulary one level away from the controller
+ * and lets every test here be a synchronous fake instead of an HTTP mock.
+ *
+ * It is also STATELESS by design: no cached challenge id, no cached prepare
+ * result, no attempt counter. A challenge is single-use and the server consumes
+ * it atomically, so there is nothing a second attempt could legitimately reuse.
+ * Statelessness is the whole of this module's obligation to "never reuse a spent
+ * challenge_id", and it is checkable by calling `prepare()` twice.
+ */
+import type { UpgradeRefreshField, UpgradeStartWire } from '../api/model';
+import type { UpgradeTransport } from './controller';
+import { type UpgradePrepared } from './factors';
+import type { UpgradeSessionPin } from './session';
+export type UpgradeTransportDeps = {
+    /** `POST /auth/upgrade/start`. Returns the raw snake_case body; rejects with `PassflowError`. */
+    startUpgrade(payload: {
+        method: string;
+        relying_party_id?: string;
+    }): Promise<UpgradeStartWire>;
+    /**
+     * `POST /auth/refresh` carrying `upgrade`. Resolves once the elevated tokens
+     * are STORED.
+     *
+     * `pin` is the session and user identity the flight began under (§13.4
+     * revision 6). The host verifies it immediately before it applies the rotated
+     * tokens and discards them on mismatch — the check has to live inside the
+     * token-applying path, because that is the only place it cannot be bypassed
+     * by another entry point. The transport only carries the value; the facade
+     * supplies it, since the flight's start is what it is pinned to.
+     */
+    commitRefresh(upgrade: UpgradeRefreshField, pin?: UpgradeSessionPin): Promise<void>;
+    /** Reports whether this delivery mode can carry an upgrade at all. BFF cannot. */
+    canCommit(): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /** Optional relying-party id for passkey upgrades; forwarded verbatim. */
+    relyingPartyId?: () => string | undefined;
+    /**
+     * Invalidates the session. Called ONLY for a commit 401 whose error id
+     * positively means the session died (`invalidatesSessionOnCommit`) — a
+     * genuine expiry during an elevation is still an expiry, and the transport is
+     * the only code that can tell, because it knows it issued the request and can
+     * read the error id. Everything else, including an id this SDK does not
+     * recognise, leaves the session alone.
+     */
+    markSessionInvalid?: () => void;
+};
+/**
+ * Normalises the prepare round's wire body.
+ *
+ * `webauthn` is passed through by reference, never re-serialised: the ceremony
+ * hands those exact bytes to the authenticator and the server re-parses them on
+ * the way back.
+ *
+ * A missing `challenge_id` or `expires_at` is a protocol violation, not an
+ * optional field. Producing `challengeId: undefined` would surface two round
+ * trips later as an opaque 401 with nothing to point at.
+ */
+export declare const toPrepared: (wire: UpgradeStartWire) => UpgradePrepared;
+/** Builds the transport. Returns the port type, so the controller stays HTTP-agnostic. */
+export declare const createUpgradeTransport: (deps: UpgradeTransportDeps) => UpgradeTransport;
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../lib/upgrade/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQrD,OAAO,EAA0E,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AACzH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,MAAM,oBAAoB,GAAG;IACjC,iGAAiG;IACjG,YAAY,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAChG;;;;;;;;;;OAUG;IACH,aAAa,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,kFAAkF;IAClF,SAAS,IAAI;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC1C;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;CACjC,CAAC;AAUF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,gBAAgB,KAAG,eAenD,CAAC;AAYF,0FAA0F;AAC1F,eAAO,MAAM,sBAAsB,GAAI,MAAM,oBAAoB,KAAG,gBA6ElE,CAAC"}

package/dist/tsconfig.build.tsbuildinfo

@@ -1 +1 @@
-{"root":["../lib/index.ts","../lib/passflow.ts","../lib/store.ts","../lib/api/app.ts","../lib/api/auth.ts","../lib/api/axios-client.ts","../lib/api/cli-auth.ts","../lib/api/index.ts","../lib/api/invitation.ts","../lib/api/model.ts","../lib/api/setting.ts","../lib/api/tenant.ts","../lib/api/two-factor.ts","../lib/api/user.ts","../lib/constants/index.ts","../lib/device/index.ts","../lib/m2m/client.ts","../lib/m2m/errors.ts","../lib/m2m/index.ts","../lib/m2m/types.ts","../lib/platform/index.ts","../lib/platform/types.ts","../lib/platform/web-adapter.ts","../lib/services/auth-service.ts","../lib/services/index.ts","../lib/services/invitation-service.ts","../lib/services/logger.ts","../lib/services/tenant-service.ts","../lib/services/tenant-user-membership.ts","../lib/services/token-cache-service.ts","../lib/services/two-factor-service.ts","../lib/services/user-service.ts","../lib/storage/index.ts","../lib/token/delivery-manager.ts","../lib/token/index.ts","../lib/token/membership.ts","../lib/token/service.ts","../lib/token/token.ts","../lib/types/index.ts","../lib/upgrade/challenge.ts","../lib/upgrade/controller.ts","../lib/upgrade/factors.ts","../lib/upgrade/index.ts","../lib/upgrade/select.ts","../lib/utils/validation.ts"],"version":"5.9.3"}
+{"root":["../lib/index.ts","../lib/passflow.ts","../lib/store.ts","../lib/api/app.ts","../lib/api/auth.ts","../lib/api/axios-client.ts","../lib/api/cli-auth.ts","../lib/api/index.ts","../lib/api/invitation.ts","../lib/api/model.ts","../lib/api/setting.ts","../lib/api/tenant.ts","../lib/api/two-factor.ts","../lib/api/upgrade.ts","../lib/api/user.ts","../lib/constants/index.ts","../lib/device/index.ts","../lib/interceptors/fetch-registry.ts","../lib/m2m/client.ts","../lib/m2m/errors.ts","../lib/m2m/index.ts","../lib/m2m/types.ts","../lib/platform/index.ts","../lib/platform/types.ts","../lib/platform/web-adapter.ts","../lib/services/auth-service.ts","../lib/services/index.ts","../lib/services/invitation-service.ts","../lib/services/logger.ts","../lib/services/tenant-service.ts","../lib/services/tenant-user-membership.ts","../lib/services/token-cache-service.ts","../lib/services/two-factor-service.ts","../lib/services/user-service.ts","../lib/storage/index.ts","../lib/token/delivery-manager.ts","../lib/token/index.ts","../lib/token/membership.ts","../lib/token/service.ts","../lib/token/token.ts","../lib/types/index.ts","../lib/upgrade/acr.ts","../lib/upgrade/axios-adapter.ts","../lib/upgrade/challenge.ts","../lib/upgrade/client.ts","../lib/upgrade/controller.ts","../lib/upgrade/core.ts","../lib/upgrade/errors.ts","../lib/upgrade/facade.ts","../lib/upgrade/factors.ts","../lib/upgrade/fetch-adapter.ts","../lib/upgrade/index.ts","../lib/upgrade/markers.ts","../lib/upgrade/replay.ts","../lib/upgrade/select.ts","../lib/upgrade/session.ts","../lib/upgrade/snapshot.ts","../lib/upgrade/transport.ts","../lib/utils/validation.ts"],"version":"5.9.3"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@passflow/core",
   "description": "Passflow JS SDK",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",