@saeris/hanko 0.0.0 → 0.2.0

package/dist/approve/index.d.mts

@@ -0,0 +1,318 @@
+import { n as ApprovalState } from "../machine-CRHKjtoP.mjs";
+import { a as buildAppSchemeUrl, c as digitalAssetLinks, d as pwaLaunchHandler, i as appleAppSiteAssociation, l as expoLinkingConfig, n as LinkSource, o as buildApprovalUrl, r as ParsedApprovalLink, s as consumeLaunchTarget, t as LinkConfig, u as parseApprovalLink } from "../linking-nKoayyHf.mjs";
+//#region src/scanner.d.ts
+/**
+ * QR reading for the approving device.
+ *
+ * Generation is dependency-free; decoding cannot be. hanko defines the
+ * {@link QrScanner} interface — two methods — and lets the host bring a
+ * decoder rather than picking one for everybody.
+ *
+ * That indirection is not ceremony. `BarcodeDetector` looks like the obvious
+ * answer and is NOT a web standard: it is a WICG incubation that MDN flags as
+ * outside Baseline, Safari has never shipped it, and no vendor has committed
+ * to it. Building against it directly means the scanner silently does nothing
+ * on an iPhone — the device most people approve from.
+ *
+ * What works today, in rough order of preference:
+ *
+ * - **`qr-scanner`** — ~6 kB gzipped, self-contained, uses a native
+ *   `BarcodeDetector` where one exists and its own worker otherwise. It owns
+ *   the camera too, which is most of the work. See the Astro example.
+ * - **`barcode-detector`** — a ponyfill over ZXing-C++/WASM. More formats and
+ *   actively maintained, but it fetches its WASM from a CDN at runtime, which
+ *   is a poor default on an authentication screen.
+ * - **`expo-camera`** on React Native, where no web API exists at all.
+ *
+ * {@link createBarcodeDetectorScanner} remains for the native path and for
+ * ponyfills mirroring that API.
+ */
+/** Minimal shape of a detected barcode. Mirrors the Barcode Detection API. */
+/**
+ * A camera frame, as an opaque handle.
+ *
+ * The DOM's `ImageBitmapSource` in a browser — a `<video>`, `ImageBitmap`,
+ * `Blob`, or canvas — but declared locally rather than pulled from `lib.dom`.
+ * This package compiles without the DOM lib on purpose, so server code cannot
+ * reach a browser-only global by accident, and so the same types work for a
+ * React Native frame that is not an `ImageBitmapSource` at all.
+ *
+ * hanko never inspects the frame; it passes it straight to the detector.
+ */
+type CameraFrame = unknown;
+/** Minimal shape of a detected barcode. Mirrors the Barcode Detection API. */
+interface DetectedBarcode {
+  rawValue: string;
+}
+/**
+ * What hanko needs from a scanner: turn a frame into strings.
+ *
+ * Deliberately narrower than `BarcodeDetector` — no bounding boxes, no
+ * formats — so an `expo-camera` or jsQR adapter is trivial to write.
+ */
+interface QrScanner {
+  detect(source: CameraFrame): Promise<DetectedBarcode[]>;
+}
+/** The subset of the global `BarcodeDetector` this module uses. */
+interface BarcodeDetectorLike {
+  detect(source: CameraFrame): Promise<DetectedBarcode[]>;
+}
+interface BarcodeDetectorConstructor {
+  new (options?: {
+    formats?: string[];
+  }): BarcodeDetectorLike;
+}
+/** Whether this runtime has a native `BarcodeDetector`. */
+declare const hasNativeBarcodeDetector: () => boolean;
+/**
+ * Scanner backed by the platform's `BarcodeDetector`.
+ *
+ * Pass the ponyfill's constructor where the native one is missing:
+ *
+ * ```ts
+ * import { BarcodeDetector } from "barcode-detector/ponyfill";
+ * const scanner = createBarcodeDetectorScanner({ detector: BarcodeDetector });
+ * ```
+ *
+ * Restricted to `qr_code`: a taplist beer can carries an EAN-13 barcode, and a
+ * scanner that reported it here would send a product code to the approval
+ * endpoint as though it were a user code.
+ */
+declare const createBarcodeDetectorScanner: ({ detector }?: {
+  /** Constructor to use. Defaults to the global when present. */
+  detector?: BarcodeDetectorConstructor;
+}) => QrScanner;
+/** Everything hanko can pull out of a scanned payload. */
+interface ScannedPayload {
+  /** The code to send to the approval endpoint. */
+  userCode: string;
+  /** The URL the QR encoded, when it was a URL. */
+  verificationUri?: string;
+}
+/**
+ * Read a `user_code` out of a scanned string.
+ *
+ * QRs in this flow carry `verification_uri_complete` — a URL with the code in
+ * it — but a scanner may also see a bare code from a hand-typed fallback, so
+ * both are accepted.
+ *
+ * Returns `null` rather than throwing: a camera pointed at the world sees
+ * unrelated codes constantly, and each one is a normal non-event, not an
+ * error.
+ */
+declare const parseScannedCode: (raw: string, { param }?: {
+  param?: string;
+}) => ScannedPayload | null;
+//#endregion
+//#region src/challenge.d.ts
+/**
+ * Confirmation challenges for the approving device.
+ *
+ * RFC 8628 §5.4: the approval screen SHOULD show the code and ask the user to
+ * verify it matches the device in front of them. Scanning a QR skips the
+ * typing, which also skips the moment where the user would have noticed the
+ * code was wrong — so the check has to be reintroduced deliberately.
+ *
+ * How much friction that check deserves is a product decision, not a protocol
+ * one. Discord and Steam ship a bare "Approve?"; GitHub's sudo flow makes you
+ * type a code; Google shows three numbers and asks you to pick the one on the
+ * other screen. All are legitimate for different risk levels, so the strategy
+ * is pluggable and the machine only cares whether it passed.
+ *
+ * These run on the ALREADY AUTHENTICATED device. They do not authenticate the
+ * user — they establish that the user can see the screen requesting access.
+ */
+/** Outcome of a challenge attempt. */
+interface ChallengeResult {
+  ok: boolean;
+  /** Present when `ok` is false, for a precise message. */
+  reason?: `mismatch` | `cancelled` | `unavailable`;
+}
+/**
+ * A confirmation strategy.
+ *
+ * `present` gives the UI whatever it needs to render (the decoys for a
+ * triplet, say); `verify` checks the user's answer. Async because a biometric
+ * or WebAuthn prompt is inherently asynchronous.
+ */
+interface ChallengeStrategy<TPrompt = unknown, TAnswer = unknown> {
+  /** Stable name, so a UI can switch on which challenge it is rendering. */
+  readonly kind: string;
+  /** What the UI should show. Called once per confirmation. */
+  present(userCode: string): TPrompt;
+  /** Check the user's answer. */
+  verify(answer: TAnswer, userCode: string): Promise<ChallengeResult>;
+}
+/**
+ * No challenge — approving is a single tap.
+ *
+ * What Discord and Steam ship. Appropriate when the QR was scanned inside your
+ * own authenticated app, which already proves possession of the phone. Note
+ * this is weaker than RFC 8628 §5.4 asks for: nothing stops a user approving a
+ * code they never actually looked at.
+ */
+declare const noChallenge: () => ChallengeStrategy<null, void>;
+/**
+ * The user types the code shown on the device.
+ *
+ * The RFC's own suggestion, and GitHub's sudo pattern. Highest friction,
+ * strongest guarantee: an attacker who phished the QR cannot supply a code the
+ * user can read off their own screen.
+ */
+declare const codeEntryChallenge: () => ChallengeStrategy<{
+  kind: `code-entry`;
+}, string>;
+/** What a triplet challenge hands the UI. */
+interface TripletPrompt {
+  kind: `triplet`;
+  /** The real code plus decoys, already shuffled. Render as-is. */
+  choices: string[];
+}
+/**
+ * The user picks the real code from a small set of decoys.
+ *
+ * Google's mobile approval pattern. Most of code-entry's guarantee at a
+ * fraction of the friction — one tap instead of eight keystrokes — which
+ * matters on a phone. A wrong pick is a real signal: the user is not looking
+ * at the device they are authorizing.
+ */
+declare const tripletChallenge: ({ decoys, generate, shuffle }: {
+  /** Decoys alongside the real code. Two gives the classic three-up. */
+  decoys?: number;
+  /** Produces a decoy. Must match the real code's shape to be plausible. */
+  generate: () => string;
+  /** Injectable for deterministic tests. */
+  shuffle?: <T>(items: T[]) => T[];
+} & {
+  generate: () => string;
+}) => ChallengeStrategy<TripletPrompt, string>;
+/**
+ * Delegate to something the platform provides — FaceID, Touch ID, WebAuthn, a
+ * device passcode.
+ *
+ * hanko cannot implement these: they are platform APIs with no common
+ * interface. What it can do is give them a slot in the same machine, so a host
+ * that has one is not forced outside the flow to use it.
+ *
+ * A biometric proves possession of the phone, NOT that the user looked at the
+ * device screen — so for a public taproom TV, pair it with `codeEntry` or
+ * `triplet` rather than using it alone.
+ */
+declare const platformChallenge: ({ kind, authenticate }: {
+  kind?: string;
+  /** Resolves true when the platform accepted the user. */
+  authenticate: (userCode: string) => Promise<boolean>;
+}) => ChallengeStrategy<{
+  kind: string;
+}, void>;
+/**
+ * Require several challenges in order.
+ *
+ * The composition that makes sense in practice: a biometric proves the phone,
+ * a code check proves the screen. Neither alone covers both.
+ *
+ * Short-circuits on the first failure, and its `present` returns every prompt
+ * so a UI can render them as steps.
+ */
+declare const allOf: (strategies: ChallengeStrategy[]) => ChallengeStrategy<unknown[], unknown[]>;
+//#endregion
+//#region src/approve/index.d.ts
+/** What the approval endpoint tells us about a code. */
+interface ResolvedGrant {
+  /** The code, as the server has it. Display this for the user to check. */
+  userCode: string;
+  /** Optional detail a host may show: which client is asking, and for what. */
+  clientId?: string;
+  scope?: string;
+}
+interface ApprovalHooks {
+  /** Any successful transition. The main binding point for a UI. */
+  onTransition?: (from: ApprovalState, to: ApprovalState) => void;
+  /** A code was read. Fires before the server is asked about it. */
+  onCode?: (userCode: string) => void;
+  /** The server resolved the code. Carries what to show the user. */
+  onResolved?: (grant: ResolvedGrant, prompt: unknown) => void;
+  /** The challenge was answered incorrectly. The user may retry. */
+  onChallengeFailed?: (reason: string | undefined, attempts: number) => void;
+  /** Terminal: the decision was recorded. */
+  onSettled?: (state: ApprovalState) => void;
+  /** Recoverable failure — camera or network. */
+  onError?: (error: unknown, state: ApprovalState) => void;
+}
+interface ApprovalClientOptions {
+  /** Resolve a code to a grant. Usually `GET /link?user_code=…`. */
+  resolve: (userCode: string) => Promise<ResolvedGrant | null>;
+  /** Record the decision. Usually `POST /link`. */
+  submit: (userCode: string, approved: boolean) => Promise<void>;
+  /**
+   * How the user proves they are looking at the requesting screen.
+   *
+   * Defaults to {@link noChallenge} — one tap, what Discord and Steam ship.
+   * For a public screen prefer `codeEntryChallenge` or `tripletChallenge`,
+   * which is what RFC 8628 §5.4 actually asks for.
+   */
+  challenge?: ChallengeStrategy;
+  /** Needed only for the in-app scanning path. */
+  scanner?: QrScanner;
+  /** Query parameter carrying the code in scanned URLs. */
+  codeParam?: string;
+  hooks?: ApprovalHooks;
+}
+declare class ApprovalClient {
+  #private;
+  constructor({ resolve, submit, challenge, scanner, codeParam, hooks }: ApprovalClientOptions);
+  get state(): ApprovalState;
+  get settled(): boolean;
+  /** The resolved grant, once known. Show its code for the user to verify. */
+  get grant(): ResolvedGrant | undefined;
+  /** Whatever the challenge wants rendered — triplet choices, a prompt kind. */
+  get challengePrompt(): unknown;
+  get challengeKind(): string;
+  /** Whether the challenge has been satisfied, so approval may proceed. */
+  get confirmed(): boolean;
+  /** Open the scanner (in-app path). */
+  startScanning(): void;
+  /**
+   * Offer a camera frame to the scanner.
+   *
+   * Returns the code when this frame contained one. Call it per frame and
+   * ignore the nulls — a camera pointed at a room sees unrelated codes
+   * constantly, and each is a non-event rather than an error.
+   */
+  scan(source: CameraFrame): Promise<string | null>;
+  /**
+   * Hand over a code from the URL (Plex path) or a manual entry field.
+   *
+   * The same entry point as a successful scan, so both topologies converge on
+   * one flow from here.
+   */
+  submitCode(userCode: string): Promise<boolean>;
+  /**
+   * Answer the confirmation challenge.
+   *
+   * Separate from {@link approve} so a UI can verify as the user types (or as
+   * a biometric returns) and enable the approve button only once it passes.
+   */
+  confirm(answer?: unknown): Promise<boolean>;
+  /**
+   * Approve the sign-in.
+   *
+   * Refuses while the challenge is unsatisfied. That guard is the point of the
+   * challenge existing: a UI bug that wires the button straight to this method
+   * must not be able to skip the check.
+   */
+  approve(): Promise<boolean>;
+  /**
+   * Refuse the sign-in.
+   *
+   * Deliberately NOT gated on the challenge. A user who cannot confirm a code
+   * is exactly the user most likely to be looking at a phishing attempt, and
+   * they must always be able to say no.
+   */
+  deny(): Promise<boolean>;
+  /** Start over after a failure or an unrecognized code. */
+  reset(): void;
+}
+//#endregion
+export { ApprovalClient, ApprovalClientOptions, ApprovalHooks, type CameraFrame, type ChallengeResult, type ChallengeStrategy, type DetectedBarcode, type LinkConfig, type LinkSource, type ParsedApprovalLink, type QrScanner, ResolvedGrant, type ScannedPayload, type TripletPrompt, allOf, appleAppSiteAssociation, buildAppSchemeUrl, buildApprovalUrl, codeEntryChallenge, consumeLaunchTarget, createBarcodeDetectorScanner, digitalAssetLinks, expoLinkingConfig, hasNativeBarcodeDetector, noChallenge, parseApprovalLink, parseScannedCode, platformChallenge, pwaLaunchHandler, tripletChallenge };
+//# sourceMappingURL=index.d.mts.map

package/dist/approve/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/scanner.ts","../../src/challenge.ts","../../src/approve/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAuCY;;UAGK;EACf;;;;;;;;UASe;EACf,OAAO,QAAQ,cAAc,QAAQ;;;UAI7B;EACR,OAAO,QAAQ,cAAc,QAAQ;;UAG7B;OACH;IAAY;MAAuB;;;cAI7B;;;;;;;;;;;;;;;cAiBA,iCAAgC;;EAI3C,WAAW;MACJ;;UA2BQ;;EAEf;;EAEA;;;;;;;;;;;;;cAcW,mBACX,eACA;EAA2B;MAC1B;;;;;;;;;;;;;;;;;;;;;UCnHc;EACf;;EAEA;;;;;;;;;UAUe,kBAAkB,mBAAmB;;WAE3C;;EAET,QAAQ,mBAAmB;;EAE3B,OAAO,QAAQ,SAAS,mBAAmB,QAAQ;;;;;;;;;;cAWxC,mBAAkB;;;;;;;;cAalB,0BAAyB;EAClC;;;UAgBa;EACf;;EAEA;;;;;;;;;;cAWW,qBAAoB,QAAA,UAAA;;EAM/B;;EAEA;;EAEA,WAAW,GAAG,OAAO,QAAQ;;EACzB;MAA2B,kBAAkB;;;;;;;;;;;;;cAoCtC,sBAAqB,MAAA;EAIhC;;EAEA,eAAe,qBAAqB;MAClC;EAAoB;;;;;;;;;;;cAyBX,QACX,YAAY,wBACX;;;;UClJc;;EAEf;;EAEA;EACA;;UAGe;;EAEf,gBAAgB,MAAM,eAAe,IAAI;;EAEzC,UAAU;;EAEV,cAAc,OAAO,eAAe;;EAEpC,qBAAqB,4BAA4B;;EAEjD,aAAa,OAAO;;EAEpB,WAAW,gBAAgB,OAAO;;UAGnB;;EAEf,UAAU,qBAAqB,QAAQ;;EAEvC,SAAS,kBAAkB,sBAAsB;;;;;;;;EAQjD,YAAY;;EAEZ,UAAU;;EAEV;EACA,QAAQ;;cAGG;;EAcC,cACV,SACA,QACA,WACA,SACA,WACA,SACC;MASC,SAAS;MAIT;;MAKA,SAAS;;MAKT;MAIA;;MAKA;;EAgBJ;;;;;;;;EAWM,KAAK,QAAQ,cAAc;;;;;;;EA6B3B,WAAW,mBAAmB;;;;;;;EAoC9B,QAAQ,mBAAmB;;;;;;;;EAyB3B,WAAW;;;;;;;;EAYX,QAAQ;;EAqBd"}