@saeris/hanko 0.0.0 → 0.2.0

package/dist/handlers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.mjs","names":[],"sources":["../src/handlers.ts"],"sourcesContent":["/**\n * Request → Response glue for the three endpoints the flow needs.\n *\n * Built on the WinterTC `Request`/`Response` pair, so the same handlers run on\n * Cloudflare Workers, Vercel Functions, Deno Deploy, Bun, and Node 18+ without\n * a framework adapter. This is the layer hanko ships so a host app writes\n * routing, not protocol.\n *\n * Stateless by construction: nothing is held between invocations. Every\n * request loads its grant from the store, applies one transition, and writes\n * it back — which is what makes this safe on an edge runtime where the next\n * request may land on a different instance, or on an instance that was frozen\n * mid-flow.\n */\n\nimport { appleAppSiteAssociation, digitalAssetLinks } from \"./linking.js\";\nimport type { HankoServer } from \"./server.js\";\n\n/** JSON with a status. Kept local so nothing imports a framework helper. */\nconst json = (body: unknown, status = 200): Response =>\n  new Response(JSON.stringify(body), {\n    status,\n    headers: {\n      \"content-type\": `application/json`,\n      // These are one-shot auth responses. A cached `authorization_pending`\n      // served to a later poll would stall the device until expiry.\n      \"cache-control\": `no-store`\n    }\n  });\n\n/**\n * Read parameters from a form body or JSON.\n *\n * RFC 8628 specifies form encoding, but hosts routinely post JSON from their\n * own front end, and rejecting that would be pedantry rather than security.\n */\nconst readParams = async (\n  request: Request\n): Promise<Partial<Record<string, string>>> => {\n  const contentType = request.headers.get(`content-type`) ?? ``;\n\n  if (contentType.includes(`application/json`)) {\n    const body: unknown = await request.json();\n    if (typeof body !== `object` || body === null) return {};\n    return Object.fromEntries(\n      Object.entries(body).map(([key, value]) => [key, String(value)])\n    );\n  }\n\n  // `URLSearchParams` over `request.formData()`: the spec sends\n  // `application/x-www-form-urlencoded`, which this parses exactly, while\n  // `formData()` drags in multipart handling that is both deprecated on the\n  // server and useless here — no field in this protocol is a file.\n  const params: Partial<Record<string, string>> = {};\n  for (const [key, value] of new URLSearchParams(await request.text())) {\n    params[key] = value;\n  }\n  return params;\n};\n\n/**\n * Hook for the rate limiting RFC 8628 §5.1 requires.\n *\n * hanko deliberately does not implement it: an effective limiter needs the IP,\n * which lives in a platform-specific header (`CF-Connecting-IP`,\n * `x-forwarded-for`), and needs storage this library should not assume. What\n * it can do is make the seam explicit so the requirement is not silently\n * skipped.\n *\n * Return `false` to reject with 429.\n */\nexport type RateLimiter = (\n  request: Request,\n  userCode: string\n) => Promise<boolean> | boolean;\n\nexport interface HandlerOptions {\n  server: HankoServer;\n  /**\n   * Identify the approving user from their session.\n   *\n   * The trust boundary of the whole flow: whatever this returns becomes the\n   * `subject` the device is signed in as. Read it from YOUR session — never\n   * from the request body, which the client controls.\n   *\n   * Return `null` when unauthenticated, and the approval endpoint answers 401.\n   */\n  authenticate: (request: Request) => Promise<string | null> | string | null;\n  /**\n   * Guard the approval endpoint. Strongly recommended — see {@link RateLimiter}.\n   */\n  rateLimit?: RateLimiter;\n}\n\n/**\n * Public origin this request actually arrived on.\n *\n * `request.url` is unreliable behind a proxy: it carries the internal host the\n * proxy forwarded to, not the one the client typed. `x-forwarded-host` and\n * `x-forwarded-proto` carry the real ones, and every common proxy sets them —\n * ngrok, Cloudflare, Vercel, nginx.\n *\n * Returns `null` when nothing usable is present, so the caller falls back to\n * its configured value rather than guessing.\n *\n * These headers are CLIENT-CONTROLLABLE when no proxy strips them, so this is\n * only safe for building a URL the same client will visit. Never use it for an\n * authorization decision.\n */\nconst forwardedOrigin = (request: Request): string | null => {\n  const host = request.headers.get(`x-forwarded-host`);\n  if (host === null || host.length === 0) return null;\n\n  // A comma-separated list when several proxies chained; the first is the\n  // original client-facing host. Each hop appends, so taking the last would\n  // give the innermost proxy — the one host guaranteed to be private.\n  const [first] = host.split(`,`);\n  const cleaned = first.trim();\n  if (cleaned.length === 0) return null;\n\n  const proto = request.headers.get(`x-forwarded-proto`)?.split(`,`)[0]?.trim();\n  return `${proto === undefined || proto.length === 0 ? `https` : proto}://${cleaned}`;\n};\n\n/**\n * The device-authorization endpoint. `POST /device/authorize`.\n *\n * Unauthenticated: the whole point is that the device has no credentials yet.\n */\nexport const createAuthorizationHandler =\n  ({\n    server,\n    verificationPath = `/link`,\n    trustForwardedHost = true\n  }: Pick<HandlerOptions, `server`> & {\n    /** Path of the approval page, appended to the detected origin. */\n    verificationPath?: string;\n    /**\n     * Derive the verification URI from the request's forwarded headers.\n     *\n     * On by default because it is what makes one deployment work across a\n     * preview URL, a custom domain, and a tunnel without a redeploy. Set false\n     * to always use the configured `verificationUri` — worth doing if your\n     * platform does not strip client-sent `x-forwarded-*` headers and you would\n     * rather pin the origin than trust them.\n     */\n    trustForwardedHost?: boolean;\n  }) =>\n  async (request: Request): Promise<Response> => {\n    if (request.method !== `POST`) {\n      return json({ error: `method_not_allowed` }, 405);\n    }\n\n    const origin = trustForwardedHost ? forwardedOrigin(request) : null;\n    const params = await readParams(request);\n    const grant = await server.requestAuthorization({\n      clientId: params.client_id,\n      scope: params.scope,\n      // Undefined falls through to the server's configured value.\n      verificationUri:\n        origin === null ? undefined : `${origin}${verificationPath}`\n    });\n    return json(grant);\n  };\n\n/**\n * The token endpoint. `POST /device/token`.\n *\n * Maps poll results onto the status codes RFC 8628 §3.5 specifies: pending and\n * slow_down are 400s carrying an error code, not 200s, because a compliant\n * client distinguishes them by body rather than status.\n */\nexport const createTokenHandler =\n  ({\n    server,\n    createSession\n  }: Pick<HandlerOptions, `server`> & {\n    /**\n     * Mint whatever credential the device should receive.\n     *\n     * hanko carries the `subject` and stops there — issuing sessions is your\n     * auth system's job, and duplicating it would make this library compete\n     * with Better-Auth instead of composing with it.\n     */\n    createSession: (subject: string) => unknown;\n  }) =>\n  async (request: Request): Promise<Response> => {\n    if (request.method !== `POST`) {\n      return json({ error: `method_not_allowed` }, 405);\n    }\n\n    const params = await readParams(request);\n    const deviceCode = params.device_code;\n    if (deviceCode === undefined) {\n      return json({ error: `invalid_request` }, 400);\n    }\n\n    const result = await server.poll(deviceCode);\n\n    switch (result.status) {\n      case `approved`:\n        return json(await createSession(result.subject));\n      case `slow_down`:\n        return json({ error: result.error, interval: result.interval }, 400);\n      case `pending`:\n      case `denied`:\n      case `expired`:\n        return json({ error: result.error }, 400);\n    }\n  };\n\n/**\n * The approval endpoint. `GET` to resolve a code, `POST` to decide.\n *\n * Both require an authenticated user: this runs on the phone that is already\n * signed in, and the identity it resolves is what the device inherits.\n */\nexport const createApprovalHandler =\n  ({ server, authenticate, rateLimit }: HandlerOptions) =>\n  async (request: Request): Promise<Response> => {\n    const subject = await authenticate(request);\n    if (subject === null) return json({ error: `unauthorized` }, 401);\n\n    if (request.method === `GET`) {\n      const userCode = new URL(request.url).searchParams.get(`user_code`);\n      if (userCode === null) return json({ error: `invalid_request` }, 400);\n\n      if (rateLimit && !(await rateLimit(request, userCode))) {\n        return json({ error: `slow_down` }, 429);\n      }\n\n      const grant = await server.lookupByUserCode(userCode);\n      // Unknown and expired collapse to one answer: distinguishing them would\n      // let an attacker probe which codes are live.\n      if (!grant || grant.status !== `pending`) {\n        return json({ error: `invalid_code` }, 404);\n      }\n\n      // Returns the code, because RFC 8628 §3.3.1 asks for exactly that:\n      //\n      //   \"The server SHOULD display the user_code to the user and ask them to\n      //    verify that it matches the user_code being displayed on the device\n      //    to confirm they are authorizing the correct device.\"\n      //\n      // The mitigation is a VISUAL comparison against a physically separate\n      // screen, not a memory test. Withholding it would leave the user\n      // approving an unlabelled request, which is strictly worse: they would\n      // have nothing to compare at all.\n      //\n      // `device_code` is never returned. That one IS a bearer credential —\n      // echoing it would let anyone who can resolve a user code redeem the\n      // grant themselves.\n      return json({\n        user_code: grant.user_code,\n        client_id: grant.clientId,\n        scope: grant.scope\n      });\n    }\n\n    if (request.method === `POST`) {\n      const params = await readParams(request);\n      const userCode = params.user_code;\n      if (userCode === undefined)\n        return json({ error: `invalid_request` }, 400);\n\n      if (rateLimit && !(await rateLimit(request, userCode))) {\n        return json({ error: `slow_down` }, 429);\n      }\n\n      // Explicit opt-in to approval. A missing field denies rather than\n      // approves: a malformed request must never grant access.\n      const approved = params.approved === `true`;\n      const result = approved\n        ? await server.approve(userCode, subject)\n        : await server.deny(userCode);\n\n      return result.ok\n        ? json({ ok: true, approved })\n        : json({ error: result.reason ?? `invalid_code` }, 400);\n    }\n\n    return json({ error: `method_not_allowed` }, 405);\n  };\n\n/**\n * All three handlers, plus a router for hosts that prefer one entry point.\n *\n * The router is a convenience — a Workers `fetch` can delegate to it wholesale\n * — but the individual handlers exist so file-based routing (Astro, Next,\n * SvelteKit) can mount each at its own path.\n */\nexport const createHandlers = (\n  options: HandlerOptions & {\n    createSession: (subject: string) => unknown;\n  }\n): {\n  authorize: (request: Request) => Promise<Response>;\n  token: (request: Request) => Promise<Response>;\n  approval: (request: Request) => Promise<Response>;\n  fetch: (request: Request) => Promise<Response>;\n} => {\n  const authorize = createAuthorizationHandler(options);\n  const token = createTokenHandler(options);\n  const approval = createApprovalHandler(options);\n\n  return {\n    authorize,\n    token,\n    approval,\n    fetch: async (request) => {\n      const { pathname } = new URL(request.url);\n      if (pathname.endsWith(`/device/authorize`)) return authorize(request);\n      if (pathname.endsWith(`/device/token`)) return token(request);\n      if (pathname.endsWith(`/link`)) return approval(request);\n      return json({ error: `not_found` }, 404);\n    }\n  };\n};\n\n/**\n * Serve the association files that make universal/app links work.\n *\n * Both must be served from the SAME origin as the approval page, over HTTPS,\n * with no redirects. Apple and Google fetch them directly; a redirect or a\n * wrong content-type makes the association fail silently, which is the usual\n * reason \"universal links don't work\" with nothing in any log to explain it.\n *\n * Mount at `/.well-known/*`. Cached rather than `no-store` — unlike the auth\n * endpoints these are static, and the platforms re-fetch them on their own\n * schedule anyway.\n */\nexport const createWellKnownHandler = ({\n  appleAppIds = [],\n  androidPackageName,\n  androidFingerprints = [],\n  paths\n}: {\n  /** `<TEAM_ID>.<BUNDLE_ID>` for each iOS app that may open these links. */\n  appleAppIds?: string[];\n  androidPackageName?: string;\n  /** SHA-256 of the PLAY-signed certificate, not the local keystore. */\n  androidFingerprints?: string[];\n  /** Paths the apps claim. Defaults to the approval route. */\n  paths?: string[];\n}) => {\n  const aasa = JSON.stringify(appleAppSiteAssociation(appleAppIds, { paths }));\n  const assetlinks =\n    androidPackageName === undefined\n      ? `[]`\n      : JSON.stringify(\n          digitalAssetLinks(androidPackageName, androidFingerprints)\n        );\n\n  return (request: Request): Response | null => {\n    const { pathname } = new URL(request.url);\n\n    // `application/json` with no extension — Apple rejects other content types,\n    // and the file deliberately has no `.json` suffix.\n    if (pathname.endsWith(`/.well-known/apple-app-site-association`)) {\n      return new Response(aasa, {\n        headers: {\n          \"content-type\": `application/json`,\n          \"cache-control\": `public, max-age=3600`\n        }\n      });\n    }\n\n    if (pathname.endsWith(`/.well-known/assetlinks.json`)) {\n      return new Response(assetlinks, {\n        headers: {\n          \"content-type\": `application/json`,\n          \"cache-control\": `public, max-age=3600`\n        }\n      });\n    }\n\n    // Null rather than 404, so a host can fall through to its own routes.\n    return null;\n  };\n};\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { _ as isGrantSettled, a as MAX_BACKOFF_SECONDS, b as pollTransition, c as PollState, d as canTransitionApproval, f as canTransitionGrant, g as isApprovalSettled, h as grantTransition, i as GrantState, l as SLOW_DOWN_INCREMENT_SECONDS, m as eventForTokenError, n as ApprovalState, o as PollContext, p as canTransitionPoll, r as GrantEvent, s as PollEvent, t as ApprovalEvent, u as approvalTransition, v as isPollSettled, y as pollContextTransition } 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, t as LinkConfig, u as parseApprovalLink } from "./linking-nKoayyHf.mjs";
+import { a as DeviceGrantStore, i as DeviceGrant, n as DeviceAuthorizationError, r as DeviceAuthorizationResponse, t as DEVICE_CODE_GRANT_TYPE } from "./types-C82lb-zX.mjs";
+import { a as createHankoServer, c as BASE20_ALPHABET, d as generateDeviceCode, f as generateUserCode, i as PollResult, l as NUMERIC_ALPHABET, n as HankoServer, o as Grant, p as normalizeUserCode, r as HankoServerOptions, s as GrantHooks, t as ApproveResult, u as UserCodeOptions } from "./server-BhoYRkCm.mjs";
+export { type ApprovalEvent, type ApprovalState, type ApproveResult, BASE20_ALPHABET, DEVICE_CODE_GRANT_TYPE, type DeviceAuthorizationError, type DeviceAuthorizationResponse, type DeviceGrant, type DeviceGrantStore, Grant, type GrantEvent, type GrantHooks, type GrantState, HankoServer, type HankoServerOptions, type LinkConfig, type LinkSource, MAX_BACKOFF_SECONDS, NUMERIC_ALPHABET, type ParsedApprovalLink, type PollContext, type PollEvent, type PollResult, type PollState, SLOW_DOWN_INCREMENT_SECONDS, type UserCodeOptions, appleAppSiteAssociation, approvalTransition, buildAppSchemeUrl, buildApprovalUrl, canTransitionApproval, canTransitionGrant, canTransitionPoll, createHankoServer, digitalAssetLinks, eventForTokenError, expoLinkingConfig, generateDeviceCode, generateUserCode, grantTransition, isApprovalSettled, isGrantSettled, isPollSettled, normalizeUserCode, parseApprovalLink, pollContextTransition, pollTransition, pwaLaunchHandler };

package/dist/index.mjs

@@ -0,0 +1,345 @@
+import { a as normalizeUserCode, i as generateUserCode, n as NUMERIC_ALPHABET, r as generateDeviceCode, t as BASE20_ALPHABET } from "./codes-Ba_qYH6u.mjs";
+import { a as canTransitionGrant, c as grantTransition, d as isPollSettled, f as pollContextTransition, i as canTransitionApproval, l as isApprovalSettled, n as SLOW_DOWN_INCREMENT_SECONDS, o as canTransitionPoll, p as pollTransition, r as approvalTransition, s as eventForTokenError, t as MAX_BACKOFF_SECONDS, u as isGrantSettled } from "./machine-D_5DAFxi.mjs";
+import { t as DEVICE_CODE_GRANT_TYPE } from "./types-BvBIFPH6.mjs";
+import { a as digitalAssetLinks, c as pwaLaunchHandler, n as buildAppSchemeUrl, o as expoLinkingConfig, r as buildApprovalUrl, s as parseApprovalLink, t as appleAppSiteAssociation } from "./linking-DcQSMgem.mjs";
+//#region src/grant.ts
+/**
+* A single authorization attempt, as an object that owns its own state.
+*
+* The state machine in `machine.ts` is pure; this class is the boundary around
+* it. `#private` fields are a genuine runtime boundary, not a compile-time
+* convention — which matters here because what is being protected is a bearer
+* credential (`device_code`) and, after approval, the identity that redeeming
+* it hands over. Nothing outside this class can reach either by accident.
+*
+* Hooks let a host app observe transitions (persist, log, push to a UI) without
+* being able to force one.
+*/
+var Grant = class Grant {
+	#deviceCode;
+	#userCode;
+	#expiresAt;
+	#clientId;
+	#scope;
+	#hooks;
+	#state;
+	#subject;
+	#interval;
+	#lastPolledAt;
+	constructor(grant, hooks = {}) {
+		this.#deviceCode = grant.device_code;
+		this.#userCode = grant.user_code;
+		this.#expiresAt = grant.expiresAt;
+		this.#clientId = grant.clientId;
+		this.#scope = grant.scope;
+		this.#state = grant.status;
+		this.#subject = grant.subject;
+		this.#interval = grant.interval;
+		this.#lastPolledAt = grant.lastPolledAt;
+		this.#hooks = hooks;
+	}
+	/** Rehydrate from a store record. */
+	static from(grant, hooks) {
+		return new Grant(grant, hooks);
+	}
+	get state() {
+		return this.#state;
+	}
+	get userCode() {
+		return this.#userCode;
+	}
+	get interval() {
+		return this.#interval;
+	}
+	get settled() {
+		return isGrantSettled(this.#state);
+	}
+	/**
+	* The approving identity — readable only once approved.
+	*
+	* Deliberately not a plain field: reading it in any other state is a caller
+	* bug, and returning `undefined` silently would let it be handed to a session
+	* factory as an empty subject.
+	*/
+	get subject() {
+		if (this.#state !== `approved` && this.#state !== `consumed`) throw new Error(`subject is not available while the grant is ${this.#state}`);
+		return this.#subject ?? ``;
+	}
+	/** Whether this grant's deadline has passed as of `now`. */
+	expired(now) {
+		return now >= this.#expiresAt;
+	}
+	/**
+	* Whether a poll at `now` arrives sooner than the agreed interval.
+	*
+	* The first poll is always allowed; only a second one inside the window is
+	* early. Used by the server to decide between `authorization_pending` and
+	* `slow_down`.
+	*/
+	pollingTooSoon(now) {
+		return this.#lastPolledAt !== void 0 && now - this.#lastPolledAt < this.#interval * 1e3;
+	}
+	/** Record that a poll happened, without changing state. */
+	markPolled(now) {
+		this.#lastPolledAt = now;
+	}
+	/**
+	* Apply `slow_down`: add 5s permanently, per RFC 8628 §3.5.
+	*
+	* A method rather than a setter — the increment is the spec's, not the
+	* caller's, and exposing the interval for assignment would invite an
+	* exponential backoff that the spec reserves for connection failures.
+	*/
+	slowDown(now) {
+		this.#interval += 5;
+		this.#lastPolledAt = now;
+		return this.#interval;
+	}
+	/**
+	* Send an event. Returns whether it moved the grant.
+	*
+	* The only way to change state. Illegal events are rejected rather than
+	* throwing: double-approval and re-redemption are things a real caller does,
+	* and they must be no-ops rather than crashes.
+	*/
+	send(event) {
+		const from = this.#state;
+		const to = grantTransition(from, event);
+		if (to === from) {
+			this.#hooks.onRejected?.(from, event.type);
+			return false;
+		}
+		if (event.type === `APPROVE`) this.#subject = event.subject;
+		this.#state = to;
+		const snapshot = this.toJSON();
+		this.#hooks.onTransition?.(from, to, snapshot);
+		switch (event.type) {
+			case `APPROVE`:
+				this.#hooks.onApproved?.(event.subject, snapshot);
+				break;
+			case `DENY`:
+				this.#hooks.onDenied?.(snapshot);
+				break;
+			case `EXPIRE`:
+				this.#hooks.onExpired?.(snapshot);
+				break;
+			case `REDEEM`: this.#hooks.onRedeemed?.(this.#subject ?? ``, snapshot);
+		}
+		return true;
+	}
+	/**
+	* Plain record for persistence.
+	*
+	* Named `toJSON` so `JSON.stringify` picks it up — but note it includes
+	* `device_code` and `subject`, so it is a store payload, not something to
+	* send to a client.
+	*/
+	toJSON() {
+		return {
+			device_code: this.#deviceCode,
+			user_code: this.#userCode,
+			status: this.#state,
+			expiresAt: this.#expiresAt,
+			interval: this.#interval,
+			clientId: this.#clientId,
+			scope: this.#scope,
+			subject: this.#subject,
+			lastPolledAt: this.#lastPolledAt
+		};
+	}
+};
+//#endregion
+//#region src/server.ts
+/**
+* Server side of the device-authorization flow (RFC 8628).
+*
+* Framework-agnostic and transport-agnostic: this module never touches HTTP.
+* Host apps wire these methods to whatever routes they like — Astro endpoints,
+* Next route handlers, Workers, Hono. That is what makes the same core usable
+* from Better-Auth, Supabase, or a bare in-memory dev server.
+*
+* hanko does not issue sessions or tokens. `approve()` records WHO approved (an
+* opaque `subject`), and a successful poll hands that subject back to the host
+* app, which mints whatever credential it already knows how to mint. Owning
+* session issuance would duplicate Better-Auth rather than integrate with it.
+*
+* State transitions live in `machine.ts` and are applied through `Grant`, which
+* owns them privately. Nothing here mutates a grant's status directly.
+*/
+var HankoServer = class {
+	#store;
+	#verificationUri;
+	#buildVerificationUriComplete;
+	#expiresInSeconds;
+	#intervalSeconds;
+	#userCodeOptions;
+	#now;
+	#hooks;
+	constructor({ store, verificationUri, buildVerificationUriComplete = (userCode, uri) => `${uri}${uri.includes(`?`) ? `&` : `?`}user_code=${encodeURIComponent(userCode)}`, expiresInSeconds = 900, intervalSeconds = 5, userCode, now = () => Date.now(), hooks = {} }) {
+		this.#store = store;
+		this.#verificationUri = verificationUri;
+		this.#buildVerificationUriComplete = buildVerificationUriComplete;
+		this.#expiresInSeconds = expiresInSeconds;
+		this.#intervalSeconds = intervalSeconds;
+		this.#userCodeOptions = userCode;
+		this.#now = now;
+		this.#hooks = hooks;
+	}
+	/**
+	* Load a grant and settle its deadline before anyone reads its state.
+	*
+	* Expiry is evaluated lazily on read rather than by a timer. A background
+	* sweep cannot be relied on: serverless instances die, and a TV left on for
+	* days outlives any interval we set. Checking at the point of use means a
+	* grant is never observed as live past its deadline, whatever the host's
+	* lifecycle looks like.
+	*/
+	async #load(record) {
+		if (!record) return null;
+		const grant = Grant.from(record, this.#hooks);
+		if (grant.expired(this.#now()) && grant.send({ type: `EXPIRE` })) await this.#store.update(grant.toJSON());
+		return grant;
+	}
+	/**
+	* Start a flow. Call from the device-authorization endpoint.
+	*
+	* Returns the spec's response shape directly, so a host route can serialize
+	* it as-is.
+	*/
+	async requestAuthorization({ clientId, scope, verificationUri = this.#verificationUri } = {}) {
+		const displayCode = generateUserCode(this.#userCodeOptions);
+		const record = {
+			device_code: generateDeviceCode(),
+			user_code: normalizeUserCode(displayCode),
+			status: `pending`,
+			expiresAt: this.#now() + this.#expiresInSeconds * 1e3,
+			interval: this.#intervalSeconds,
+			clientId,
+			scope
+		};
+		await this.#store.create(record);
+		await this.#store.prune?.(this.#now());
+		return {
+			device_code: record.device_code,
+			user_code: displayCode,
+			verification_uri: verificationUri,
+			verification_uri_complete: this.#buildVerificationUriComplete(displayCode, verificationUri),
+			expires_in: this.#expiresInSeconds,
+			interval: this.#intervalSeconds
+		};
+	}
+	/**
+	* Poll for a decision. Call from the token endpoint.
+	*
+	* Enforces the interval: polling faster than allowed returns `slow_down` and
+	* permanently raises this grant's interval by 5s, per §3.5. The increase is
+	* additive and sticky — NOT exponential backoff, which the spec reserves for
+	* connection timeouts.
+	*/
+	async poll(deviceCode) {
+		const grant = await this.#load(await this.#store.findByDeviceCode(deviceCode));
+		if (!grant) return {
+			status: `expired`,
+			error: `expired_token`
+		};
+		switch (grant.state) {
+			case `denied`: return {
+				status: `denied`,
+				error: `access_denied`
+			};
+			case `consumed`:
+			case `expired`: return {
+				status: `expired`,
+				error: `expired_token`
+			};
+			case `approved`: {
+				const { subject } = grant;
+				grant.send({ type: `REDEEM` });
+				await this.#store.update(grant.toJSON());
+				return {
+					status: `approved`,
+					subject
+				};
+			}
+			case `pending`: {
+				const at = this.#now();
+				if (grant.pollingTooSoon(at)) {
+					const interval = grant.slowDown(at);
+					await this.#store.update(grant.toJSON());
+					return {
+						status: `slow_down`,
+						error: `slow_down`,
+						interval
+					};
+				}
+				grant.markPolled(at);
+				await this.#store.update(grant.toJSON());
+				return {
+					status: `pending`,
+					error: `authorization_pending`
+				};
+			}
+		}
+	}
+	/**
+	* Look up a grant by the code the user typed or arrived with.
+	*
+	* The approval page MUST display the returned `user_code` back to the user so
+	* they can confirm it matches the screen — RFC 8628 §5.4. That check is the
+	* only defense against a phished QR pointing at an attacker's device, so it
+	* is not optional UI polish.
+	*/
+	async lookupByUserCode(input) {
+		return (await this.#load(await this.#store.findByUserCode(normalizeUserCode(input))))?.toJSON() ?? null;
+	}
+	/** Record approval. `subject` is opaque to hanko; it is echoed back on poll. */
+	async approve(input, subject) {
+		return this.#decide(input, {
+			type: `APPROVE`,
+			subject
+		});
+	}
+	/** Record denial, so the device can stop polling and say why. */
+	async deny(input) {
+		return this.#decide(input, { type: `DENY` });
+	}
+	/**
+	* Shared path for approve/deny.
+	*
+	* Both are the same operation modulo the event, and the machine — not a
+	* ladder of guard clauses here — decides whether the move is legal. That is
+	* what makes approving a denied grant, or re-deciding a consumed one,
+	* impossible rather than merely checked for.
+	*/
+	async #decide(input, event) {
+		const grant = await this.#load(await this.#store.findByUserCode(normalizeUserCode(input)));
+		if (!grant) return {
+			ok: false,
+			reason: `not_found`
+		};
+		if (!grant.send(event)) return {
+			ok: false,
+			reason: reasonFor(grant.state),
+			grant: grant.toJSON()
+		};
+		const snapshot = grant.toJSON();
+		await this.#store.update(snapshot);
+		return {
+			ok: true,
+			grant: snapshot
+		};
+	}
+};
+/** Why a decision was refused, from the state that refused it. */
+const reasonFor = (state) => state === `expired` ? `expired` : `already_resolved`;
+/**
+* Factory kept for ergonomics and backwards compatibility.
+*
+* The class is the real API; this is sugar for callers who prefer not to write
+* `new`, and it keeps existing call sites working.
+*/
+const createHankoServer = (options) => new HankoServer(options);
+//#endregion
+export { BASE20_ALPHABET, DEVICE_CODE_GRANT_TYPE, Grant, HankoServer, MAX_BACKOFF_SECONDS, NUMERIC_ALPHABET, SLOW_DOWN_INCREMENT_SECONDS, appleAppSiteAssociation, approvalTransition, buildAppSchemeUrl, buildApprovalUrl, canTransitionApproval, canTransitionGrant, canTransitionPoll, createHankoServer, digitalAssetLinks, eventForTokenError, expoLinkingConfig, generateDeviceCode, generateUserCode, grantTransition, isApprovalSettled, isGrantSettled, isPollSettled, normalizeUserCode, parseApprovalLink, pollContextTransition, pollTransition, pwaLaunchHandler };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["#deviceCode","#userCode","#expiresAt","#clientId","#scope","#hooks","#state","#subject","#interval","#lastPolledAt","#store","#verificationUri","#buildVerificationUriComplete","#expiresInSeconds","#intervalSeconds","#userCodeOptions","#now","#hooks","#load","#decide"],"sources":["../src/grant.ts","../src/server.ts"],"sourcesContent":["/**\n * A single authorization attempt, as an object that owns its own state.\n *\n * The state machine in `machine.ts` is pure; this class is the boundary around\n * it. `#private` fields are a genuine runtime boundary, not a compile-time\n * convention — which matters here because what is being protected is a bearer\n * credential (`device_code`) and, after approval, the identity that redeeming\n * it hands over. Nothing outside this class can reach either by accident.\n *\n * Hooks let a host app observe transitions (persist, log, push to a UI) without\n * being able to force one.\n */\n\nimport {\n  grantTransition,\n  isGrantSettled,\n  type GrantEvent,\n  type GrantState\n} from \"./machine.js\";\nimport type { DeviceGrant } from \"./types.js\";\n\n/** Observers of a grant's lifecycle. All optional, all fire after the move. */\nexport interface GrantHooks {\n  /** Any successful transition. */\n  onTransition?: (from: GrantState, to: GrantState, grant: DeviceGrant) => void;\n  /** The user authorized. `subject` is whoever they are to the host app. */\n  onApproved?: (subject: string, grant: DeviceGrant) => void;\n  /** The user refused. */\n  onDenied?: (grant: DeviceGrant) => void;\n  /** The deadline passed without a decision, or before redemption. */\n  onExpired?: (grant: DeviceGrant) => void;\n  /** The device redeemed its approval. Terminal. */\n  onRedeemed?: (subject: string, grant: DeviceGrant) => void;\n  /**\n   * An event the current state does not accept.\n   *\n   * Not an error — a device polling twice in a row legitimately produces one —\n   * but worth surfacing, since a burst of them means a confused caller.\n   */\n  onRejected?: (state: GrantState, event: GrantEvent[`type`]) => void;\n}\n\nexport class Grant {\n  readonly #deviceCode: string;\n  readonly #userCode: string;\n  readonly #expiresAt: number;\n  readonly #clientId: string | undefined;\n  readonly #scope: string | undefined;\n  readonly #hooks: GrantHooks;\n\n  #state: GrantState;\n  #subject: string | undefined;\n  #interval: number;\n  #lastPolledAt: number | undefined;\n\n  constructor(grant: DeviceGrant, hooks: GrantHooks = {}) {\n    this.#deviceCode = grant.device_code;\n    this.#userCode = grant.user_code;\n    this.#expiresAt = grant.expiresAt;\n    this.#clientId = grant.clientId;\n    this.#scope = grant.scope;\n    this.#state = grant.status;\n    this.#subject = grant.subject;\n    this.#interval = grant.interval;\n    this.#lastPolledAt = grant.lastPolledAt;\n    this.#hooks = hooks;\n  }\n\n  /** Rehydrate from a store record. */\n  static from(grant: DeviceGrant, hooks?: GrantHooks): Grant {\n    return new Grant(grant, hooks);\n  }\n\n  get state(): GrantState {\n    return this.#state;\n  }\n\n  get userCode(): string {\n    return this.#userCode;\n  }\n\n  get interval(): number {\n    return this.#interval;\n  }\n\n  get settled(): boolean {\n    return isGrantSettled(this.#state);\n  }\n\n  /**\n   * The approving identity — readable only once approved.\n   *\n   * Deliberately not a plain field: reading it in any other state is a caller\n   * bug, and returning `undefined` silently would let it be handed to a session\n   * factory as an empty subject.\n   */\n  get subject(): string {\n    if (this.#state !== `approved` && this.#state !== `consumed`) {\n      throw new Error(\n        `subject is not available while the grant is ${this.#state}`\n      );\n    }\n    return this.#subject ?? ``;\n  }\n\n  /** Whether this grant's deadline has passed as of `now`. */\n  expired(now: number): boolean {\n    return now >= this.#expiresAt;\n  }\n\n  /**\n   * Whether a poll at `now` arrives sooner than the agreed interval.\n   *\n   * The first poll is always allowed; only a second one inside the window is\n   * early. Used by the server to decide between `authorization_pending` and\n   * `slow_down`.\n   */\n  pollingTooSoon(now: number): boolean {\n    return (\n      this.#lastPolledAt !== undefined &&\n      now - this.#lastPolledAt < this.#interval * 1000\n    );\n  }\n\n  /** Record that a poll happened, without changing state. */\n  markPolled(now: number): void {\n    this.#lastPolledAt = now;\n  }\n\n  /**\n   * Apply `slow_down`: add 5s permanently, per RFC 8628 §3.5.\n   *\n   * A method rather than a setter — the increment is the spec's, not the\n   * caller's, and exposing the interval for assignment would invite an\n   * exponential backoff that the spec reserves for connection failures.\n   */\n  slowDown(now: number): number {\n    this.#interval += 5;\n    this.#lastPolledAt = now;\n    return this.#interval;\n  }\n\n  /**\n   * Send an event. Returns whether it moved the grant.\n   *\n   * The only way to change state. Illegal events are rejected rather than\n   * throwing: double-approval and re-redemption are things a real caller does,\n   * and they must be no-ops rather than crashes.\n   */\n  send(event: GrantEvent): boolean {\n    const from = this.#state;\n    const to = grantTransition(from, event);\n\n    if (to === from) {\n      this.#hooks.onRejected?.(from, event.type);\n      return false;\n    }\n\n    // Set before hooks fire, so an observer that reads the grant sees the new\n    // state rather than the one it just left.\n    if (event.type === `APPROVE`) this.#subject = event.subject;\n    this.#state = to;\n\n    const snapshot = this.toJSON();\n    this.#hooks.onTransition?.(from, to, snapshot);\n\n    switch (event.type) {\n      case `APPROVE`:\n        this.#hooks.onApproved?.(event.subject, snapshot);\n        break;\n      case `DENY`:\n        this.#hooks.onDenied?.(snapshot);\n        break;\n      case `EXPIRE`:\n        this.#hooks.onExpired?.(snapshot);\n        break;\n      case `REDEEM`:\n        this.#hooks.onRedeemed?.(this.#subject ?? ``, snapshot);\n        break;\n    }\n\n    return true;\n  }\n\n  /**\n   * Plain record for persistence.\n   *\n   * Named `toJSON` so `JSON.stringify` picks it up — but note it includes\n   * `device_code` and `subject`, so it is a store payload, not something to\n   * send to a client.\n   */\n  toJSON(): DeviceGrant {\n    return {\n      device_code: this.#deviceCode,\n      user_code: this.#userCode,\n      status: this.#state,\n      expiresAt: this.#expiresAt,\n      interval: this.#interval,\n      clientId: this.#clientId,\n      scope: this.#scope,\n      subject: this.#subject,\n      lastPolledAt: this.#lastPolledAt\n    };\n  }\n}\n","/**\n * Server side of the device-authorization flow (RFC 8628).\n *\n * Framework-agnostic and transport-agnostic: this module never touches HTTP.\n * Host apps wire these methods to whatever routes they like — Astro endpoints,\n * Next route handlers, Workers, Hono. That is what makes the same core usable\n * from Better-Auth, Supabase, or a bare in-memory dev server.\n *\n * hanko does not issue sessions or tokens. `approve()` records WHO approved (an\n * opaque `subject`), and a successful poll hands that subject back to the host\n * app, which mints whatever credential it already knows how to mint. Owning\n * session issuance would duplicate Better-Auth rather than integrate with it.\n *\n * State transitions live in `machine.ts` and are applied through `Grant`, which\n * owns them privately. Nothing here mutates a grant's status directly.\n */\n\nimport {\n  generateDeviceCode,\n  generateUserCode,\n  normalizeUserCode\n} from \"./codes.js\";\nimport type { UserCodeOptions } from \"./codes.js\";\nimport { Grant, type GrantHooks } from \"./grant.js\";\nimport type { GrantState } from \"./machine.js\";\nimport type {\n  DeviceAuthorizationError,\n  DeviceAuthorizationResponse,\n  DeviceGrant,\n  DeviceGrantStore\n} from \"./types.js\";\n\nexport interface HankoServerOptions {\n  /** Where grants live. Use `MemoryDeviceGrantStore` for dev. */\n  store: DeviceGrantStore;\n  /**\n   * Absolute URL the user visits to approve, e.g. `https://example.com/link`.\n   * Shown on the device verbatim, so keep it short and typeable.\n   */\n  verificationUri: string;\n  /**\n   * Builds the QR target. Defaults to `${verificationUri}?user_code=${code}`.\n   * Override if your approval page reads the code from a path segment.\n   */\n  buildVerificationUriComplete?: (\n    userCode: string,\n    verificationUri: string\n  ) => string;\n  /** Code lifetime in seconds. Default 900 (15 min). */\n  expiresInSeconds?: number;\n  /** Starting poll interval in seconds. Spec default 5. */\n  intervalSeconds?: number;\n  /** Shape of the user code. See {@link UserCodeOptions}. */\n  userCode?: UserCodeOptions;\n  /** Injectable clock. Tests pass a fake; production leaves it alone. */\n  now?: () => number;\n  /**\n   * Lifecycle observers, applied to every grant this server handles.\n   *\n   * The integration seam for host frameworks: persist to a second store, emit\n   * telemetry, push to a websocket. Hooks observe; they cannot force a\n   * transition.\n   */\n  hooks?: GrantHooks;\n}\n\n/** Discriminated result of a poll. Callers switch on `status`. */\nexport type PollResult =\n  | {\n      status: `pending`;\n      error: Extract<DeviceAuthorizationError, `authorization_pending`>;\n    }\n  | {\n      status: `slow_down`;\n      error: Extract<DeviceAuthorizationError, `slow_down`>;\n      interval: number;\n    }\n  | {\n      status: `denied`;\n      error: Extract<DeviceAuthorizationError, `access_denied`>;\n    }\n  | {\n      status: `expired`;\n      error: Extract<DeviceAuthorizationError, `expired_token`>;\n    }\n  | { status: `approved`; subject: string };\n\nexport interface ApproveResult {\n  ok: boolean;\n  /** Present when `ok` is false. Lets callers show a precise message. */\n  reason?: `not_found` | `expired` | `already_resolved`;\n  grant?: DeviceGrant;\n}\n\nexport class HankoServer {\n  readonly #store: DeviceGrantStore;\n  readonly #verificationUri: string;\n  readonly #buildVerificationUriComplete: (\n    userCode: string,\n    verificationUri: string\n  ) => string;\n  readonly #expiresInSeconds: number;\n  readonly #intervalSeconds: number;\n  readonly #userCodeOptions: UserCodeOptions | undefined;\n  readonly #now: () => number;\n  readonly #hooks: GrantHooks;\n\n  constructor({\n    store,\n    verificationUri,\n    buildVerificationUriComplete = (userCode, uri): string =>\n      `${uri}${uri.includes(`?`) ? `&` : `?`}user_code=${encodeURIComponent(userCode)}`,\n    expiresInSeconds = 900,\n    intervalSeconds = 5,\n    userCode,\n    now = (): number => Date.now(),\n    hooks = {}\n  }: HankoServerOptions) {\n    this.#store = store;\n    this.#verificationUri = verificationUri;\n    this.#buildVerificationUriComplete = buildVerificationUriComplete;\n    this.#expiresInSeconds = expiresInSeconds;\n    this.#intervalSeconds = intervalSeconds;\n    this.#userCodeOptions = userCode;\n    this.#now = now;\n    this.#hooks = hooks;\n  }\n\n  /**\n   * Load a grant and settle its deadline before anyone reads its state.\n   *\n   * Expiry is evaluated lazily on read rather than by a timer. A background\n   * sweep cannot be relied on: serverless instances die, and a TV left on for\n   * days outlives any interval we set. Checking at the point of use means a\n   * grant is never observed as live past its deadline, whatever the host's\n   * lifecycle looks like.\n   */\n  async #load(record: DeviceGrant | null): Promise<Grant | null> {\n    if (!record) return null;\n\n    const grant = Grant.from(record, this.#hooks);\n    // Sent unconditionally: the machine decides whether EXPIRE is legal in the\n    // current state, so this correctly expires a stale `approved` grant that\n    // was never redeemed, not just a `pending` one.\n    if (grant.expired(this.#now()) && grant.send({ type: `EXPIRE` })) {\n      await this.#store.update(grant.toJSON());\n    }\n    return grant;\n  }\n\n  /**\n   * Start a flow. Call from the device-authorization endpoint.\n   *\n   * Returns the spec's response shape directly, so a host route can serialize\n   * it as-is.\n   */\n  async requestAuthorization({\n    clientId,\n    scope,\n    verificationUri = this.#verificationUri\n  }: {\n    clientId?: string;\n    scope?: string;\n    /**\n     * Override the configured verification URI for this grant.\n     *\n     * One deployment is commonly reachable through several hostnames — a\n     * preview URL, a custom domain, a tunnel — and the QR has to encode the one\n     * the device is actually talking to. Derive it from the incoming request\n     * (`x-forwarded-host` behind a proxy) and the code always points somewhere\n     * reachable, with no redeploy when the hostname changes.\n     */\n    verificationUri?: string;\n  } = {}): Promise<DeviceAuthorizationResponse> {\n    const displayCode = generateUserCode(this.#userCodeOptions);\n    const record: DeviceGrant = {\n      device_code: generateDeviceCode(),\n      // Stored normalized so lookup never depends on the display format.\n      user_code: normalizeUserCode(displayCode),\n      status: `pending`,\n      expiresAt: this.#now() + this.#expiresInSeconds * 1000,\n      interval: this.#intervalSeconds,\n      clientId,\n      scope\n    };\n    await this.#store.create(record);\n    await this.#store.prune?.(this.#now());\n\n    return {\n      device_code: record.device_code,\n      // The DISPLAY form goes on the wire — the device shows it verbatim.\n      user_code: displayCode,\n      verification_uri: verificationUri,\n      verification_uri_complete: this.#buildVerificationUriComplete(\n        displayCode,\n        verificationUri\n      ),\n      expires_in: this.#expiresInSeconds,\n      interval: this.#intervalSeconds\n    };\n  }\n\n  /**\n   * Poll for a decision. Call from the token endpoint.\n   *\n   * Enforces the interval: polling faster than allowed returns `slow_down` and\n   * permanently raises this grant's interval by 5s, per §3.5. The increase is\n   * additive and sticky — NOT exponential backoff, which the spec reserves for\n   * connection timeouts.\n   */\n  async poll(deviceCode: string): Promise<PollResult> {\n    const grant = await this.#load(\n      await this.#store.findByDeviceCode(deviceCode)\n    );\n    // An unknown device_code is reported as expired rather than \"not found\":\n    // distinguishing them would confirm which codes exist to an attacker.\n    if (!grant) return { status: `expired`, error: `expired_token` };\n\n    switch (grant.state) {\n      case `denied`:\n        return { status: `denied`, error: `access_denied` };\n      // A consumed grant reports as expired: a device_code is a bearer\n      // credential, so a replayed poll must not hand out the subject twice.\n      case `consumed`:\n      case `expired`:\n        return { status: `expired`, error: `expired_token` };\n      case `approved`: {\n        // Read the subject BEFORE redeeming — `consumed` still permits it, but\n        // ordering it this way keeps the read adjacent to the state that earned\n        // it rather than depending on `consumed` staying readable.\n        const { subject } = grant;\n        grant.send({ type: `REDEEM` });\n        await this.#store.update(grant.toJSON());\n        return { status: `approved`, subject };\n      }\n      case `pending`: {\n        const at = this.#now();\n        if (grant.pollingTooSoon(at)) {\n          const interval = grant.slowDown(at);\n          await this.#store.update(grant.toJSON());\n          return { status: `slow_down`, error: `slow_down`, interval };\n        }\n        grant.markPolled(at);\n        await this.#store.update(grant.toJSON());\n        return { status: `pending`, error: `authorization_pending` };\n      }\n    }\n  }\n\n  /**\n   * Look up a grant by the code the user typed or arrived with.\n   *\n   * The approval page MUST display the returned `user_code` back to the user so\n   * they can confirm it matches the screen — RFC 8628 §5.4. That check is the\n   * only defense against a phished QR pointing at an attacker's device, so it\n   * is not optional UI polish.\n   */\n  async lookupByUserCode(input: string): Promise<DeviceGrant | null> {\n    const grant = await this.#load(\n      await this.#store.findByUserCode(normalizeUserCode(input))\n    );\n    return grant?.toJSON() ?? null;\n  }\n\n  /** Record approval. `subject` is opaque to hanko; it is echoed back on poll. */\n  async approve(input: string, subject: string): Promise<ApproveResult> {\n    return this.#decide(input, { type: `APPROVE`, subject });\n  }\n\n  /** Record denial, so the device can stop polling and say why. */\n  async deny(input: string): Promise<ApproveResult> {\n    return this.#decide(input, { type: `DENY` });\n  }\n\n  /**\n   * Shared path for approve/deny.\n   *\n   * Both are the same operation modulo the event, and the machine — not a\n   * ladder of guard clauses here — decides whether the move is legal. That is\n   * what makes approving a denied grant, or re-deciding a consumed one,\n   * impossible rather than merely checked for.\n   */\n  async #decide(\n    input: string,\n    event: { type: `APPROVE`; subject: string } | { type: `DENY` }\n  ): Promise<ApproveResult> {\n    const grant = await this.#load(\n      await this.#store.findByUserCode(normalizeUserCode(input))\n    );\n    if (!grant) return { ok: false, reason: `not_found` };\n\n    if (!grant.send(event)) {\n      return {\n        ok: false,\n        reason: reasonFor(grant.state),\n        grant: grant.toJSON()\n      };\n    }\n\n    const snapshot = grant.toJSON();\n    await this.#store.update(snapshot);\n    return { ok: true, grant: snapshot };\n  }\n}\n\n/** Why a decision was refused, from the state that refused it. */\nconst reasonFor = (state: GrantState): `expired` | `already_resolved` =>\n  state === `expired` ? `expired` : `already_resolved`;\n\n/**\n * Factory kept for ergonomics and backwards compatibility.\n *\n * The class is the real API; this is sugar for callers who prefer not to write\n * `new`, and it keeps existing call sites working.\n */\nexport const createHankoServer = (options: HankoServerOptions): HankoServer =>\n  new HankoServer(options);\n"],"mappings":"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"}

package/dist/linking-DcQSMgem.mjs

@@ -0,0 +1,177 @@
+//#region src/linking.ts
+/**
+* Build the URL a QR should encode.
+*
+* Deliberately an `https://` URL rather than a scheme: this is the same string
+* `verification_uri_complete` already carries, which is what lets one QR serve
+* a phone with the app, a phone without it, and a laptop.
+*/
+const buildApprovalUrl = (userCode, { origin, path = `/link`, codeParam = `user_code` }) => {
+	const url = new URL(path, origin);
+	url.searchParams.set(codeParam, userCode);
+	return url.toString();
+};
+/**
+* Build the custom-scheme equivalent.
+*
+* For a "Open in app" button on the web fallback page — a deliberate tap, where
+* a failure is recoverable because the user is already looking at a working web
+* page. Never for the QR itself.
+*/
+const buildAppSchemeUrl = (userCode, { scheme, path = `/link`, codeParam = `user_code` }) => {
+	if (scheme === void 0) throw new Error(`no custom scheme configured`);
+	const url = new URL(`${scheme}://${path.replace(/^\//u, ``)}`);
+	url.searchParams.set(codeParam, userCode);
+	return url.toString();
+};
+/**
+* Parse an inbound link, however it arrived.
+*
+* One entry point for every route into the approval screen: an Expo
+* `Linking.getInitialURL()`, a PWA `launchQueue` target, or `location.href`.
+* Returning the `source` lets a host tell "the OS routed this to us" from "the
+* user is on the web page", which changes what the UI should offer.
+*/
+/**
+* Read a code out of a path-style link (`/link/WDJB-MJHT`).
+*
+* A web URL needs a segment BEYOND the route itself. `/link` alone would
+* otherwise yield the code "link" — which the server rejects, so an ordinary
+* visit to the approval page reports itself as a failed code. That shipped
+* once: it showed "that code is not valid" on load and tore down the camera
+* that was mid-startup.
+*
+* A custom-scheme link has no route to strip — `hanko://WDJB-MJHT` carries the
+* code as its only segment — so one segment is enough there.
+*/
+const pathCode = (url, isCustomScheme) => {
+	const segments = url.pathname.split(`/`).filter(Boolean);
+	if (isCustomScheme && segments.length === 0) return url.hostname.length > 0 ? url.hostname : void 0;
+	return segments.length >= (isCustomScheme ? 1 : 2) ? segments[segments.length - 1] : void 0;
+};
+const parseApprovalLink = (href, { codeParam = `user_code`, scheme } = {}) => {
+	let url;
+	try {
+		url = new URL(href);
+	} catch {
+		return null;
+	}
+	const isCustomScheme = scheme !== void 0 && url.protocol === `${scheme}:`;
+	if (!isCustomScheme && url.protocol !== `https:` && url.protocol !== `http:`) return null;
+	const userCode = url.searchParams.get(codeParam) ?? pathCode(url, isCustomScheme);
+	if (userCode === void 0 || userCode.length === 0) return null;
+	return {
+		userCode,
+		href,
+		source: isCustomScheme ? `custom-scheme` : `web`
+	};
+};
+/**
+* Apple App Site Association, for `/.well-known/apple-app-site-association`.
+*
+* Serve as `application/json` over HTTPS with **no redirects** — Apple fetches
+* it directly and a redirect makes the association fail silently, which is the
+* single most common reason universal links "just don't work".
+*
+* @param appIds `<TEAM_ID>.<BUNDLE_ID>`, e.g. `QQ57RJ5UTD.gg.saeris.beerjournal`
+*/
+const appleAppSiteAssociation = (appIds, { paths = [`/link`, `/link/*`] } = {}) => ({ applinks: {
+	apps: [],
+	details: appIds.map((appID) => ({
+		appID,
+		paths
+	}))
+} });
+/**
+* Digital Asset Links, for `/.well-known/assetlinks.json`.
+*
+* @param fingerprints SHA-256 of the app's SIGNING certificate. Note that Play
+*   App Signing re-signs the upload, so the fingerprint that works in
+*   production is the one from the Play Console — not your local keystore. A
+*   local-only fingerprint is why app links commonly work in debug and break
+*   after release.
+*/
+const digitalAssetLinks = (packageName, fingerprints) => [{
+	relation: [`delegate_permission/common.handle_all_urls`],
+	target: {
+		namespace: `android_app`,
+		package_name: packageName,
+		sha256_cert_fingerprints: fingerprints
+	}
+}];
+/**
+* Expo app config fragment for universal/app links.
+*
+* Merge into `app.json`. Requires a development or production build — the
+* entitlement is registered at build time, so **universal links do not work in
+* Expo Go**, and a project pinned to Expo Go must use the web fallback until it
+* moves to dev builds.
+*/
+const expoLinkingConfig = ({ origin, path = `/link`, scheme }) => {
+	const { host } = new URL(origin);
+	return {
+		...scheme === void 0 ? {} : { scheme },
+		ios: { associatedDomains: [`applinks:${host}`] },
+		android: { intentFilters: [{
+			action: `VIEW`,
+			autoVerify: true,
+			data: [{
+				scheme: `https`,
+				host,
+				pathPrefix: path
+			}],
+			category: [`BROWSABLE`, `DEFAULT`]
+		}] }
+	};
+};
+/**
+* `launch_handler` fragment for a PWA manifest.
+*
+* `navigate-existing` so a scanned link reuses the already-open window rather
+* than stacking a second one. An approval screen that opened behind the window
+* the user was already looking at would appear not to have worked at all.
+*
+* Pair with `window.launchQueue.setConsumer()` to read the target URL — see
+* {@link consumeLaunchTarget}.
+*/
+const pwaLaunchHandler = () => ({ launch_handler: { client_mode: `navigate-existing` } });
+/**
+* Read the URL an installed PWA was launched with.
+*
+* With `navigate-existing`, the window is reused and `location.href` may
+* already be correct — but when the app was cold-started or the consumer runs
+* before navigation settles, `launchQueue` is the only reliable source.
+*
+* Where `launchQueue` is unsupported — Safari and Firefox, as of 2026 — this
+* calls back with the current location ONLY when `fallbackToLocation` is set.
+* It defaults to false because the fallback cannot tell a launch from an
+* ordinary page load: it fires on every visit, and a caller that treats the
+* result as "the user just arrived from a link" will act on a URL nobody
+* followed. Opt in when the page is only ever reached by launch.
+*/
+const consumeLaunchTarget = (onTarget, { currentHref, fallbackToLocation = false } = {}) => {
+	const scope = globalThis;
+	const location = scope.location;
+	const currentLocationHref = typeof location === `object` && location !== null && `href` in location && typeof location.href === `string` ? location.href : void 0;
+	const fallback = currentHref ?? currentLocationHref;
+	const queue = scope.launchQueue;
+	if (!isLaunchQueue(queue)) {
+		if (fallbackToLocation && fallback !== void 0) onTarget(fallback);
+		return;
+	}
+	queue.setConsumer(({ targetURL }) => {
+		const href = targetURL ?? fallback;
+		if (href !== void 0) onTarget(href);
+	});
+};
+/**
+* Structural check for the Launch Handler API.
+*
+* A predicate rather than a cast: the API is absent on every server runtime and
+* in Safari and Firefox, so its presence is a runtime fact to test.
+*/
+const isLaunchQueue = (value) => typeof value === `object` && value !== null && `setConsumer` in value && typeof value.setConsumer === `function`;
+//#endregion
+export { digitalAssetLinks as a, pwaLaunchHandler as c, consumeLaunchTarget as i, buildAppSchemeUrl as n, expoLinkingConfig as o, buildApprovalUrl as r, parseApprovalLink as s, appleAppSiteAssociation as t };
+
+//# sourceMappingURL=linking-DcQSMgem.mjs.map

package/dist/linking-DcQSMgem.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"linking-DcQSMgem.mjs","names":[],"sources":["../src/linking.ts"],"sourcesContent":["/**\n * App-opening for scanned QR codes.\n *\n * The goal: one QR payload that opens a native app when it is installed, and a\n * web page when it is not — without the device ever showing an error.\n *\n * That rules out custom schemes as the primary target. A `myapp://` QR read by\n * the OS camera on a phone without the app fails silently and\n * unrecoverably — the user sees \"cannot open\" and has nowhere to go. Universal\n * Links (iOS) and App Links (Android) solve this by making the payload an\n * ordinary `https://` URL that the OS *routes* to the app when the domain and\n * app are associated, and to the browser when they are not.\n *\n * So the QR keeps encoding `verification_uri_complete` exactly as before. The\n * routing lives in association files served from the same origin, not in a\n * different payload. What this module provides is the association files, the\n * URL parsing on the receiving end, and a custom-scheme fallback for the cases\n * that genuinely need one.\n */\n\n/** Where an inbound approval link came from. */\nexport type LinkSource =\n  /** A Universal Link / App Link that opened the native app. */\n  | `app-link`\n  /** A custom scheme (`myapp://`). Only reached when explicitly used. */\n  | `custom-scheme`\n  /** An ordinary web navigation — the app was not installed, or this is a PWA. */\n  | `web`;\n\nexport interface ParsedApprovalLink {\n  userCode: string;\n  source: LinkSource;\n  /** The full URL, for logging or to hand to a router. */\n  href: string;\n}\n\nexport interface LinkConfig {\n  /**\n   * Origin serving the approval page, e.g. `https://example.com`.\n   * Must be HTTPS: both Apple and Google refuse to associate a plain-HTTP domain.\n   */\n  origin: string;\n  /** Path of the approval page. Also the path the association files claim. */\n  path?: string;\n  /** Query parameter carrying the code. */\n  codeParam?: string;\n  /**\n   * Custom scheme, e.g. `beerjournal`. Optional and NOT the primary path.\n   *\n   * Worth registering anyway: it is the only way to reach the app from\n   * contexts that refuse to follow universal links — some in-app browsers, and\n   * a few QR readers that strip them.\n   */\n  scheme?: string;\n}\n\n/**\n * Build the URL a QR should encode.\n *\n * Deliberately an `https://` URL rather than a scheme: this is the same string\n * `verification_uri_complete` already carries, which is what lets one QR serve\n * a phone with the app, a phone without it, and a laptop.\n */\nexport const buildApprovalUrl = (\n  userCode: string,\n  { origin, path = `/link`, codeParam = `user_code` }: LinkConfig\n): string => {\n  const url = new URL(path, origin);\n  url.searchParams.set(codeParam, userCode);\n  return url.toString();\n};\n\n/**\n * Build the custom-scheme equivalent.\n *\n * For a \"Open in app\" button on the web fallback page — a deliberate tap, where\n * a failure is recoverable because the user is already looking at a working web\n * page. Never for the QR itself.\n */\nexport const buildAppSchemeUrl = (\n  userCode: string,\n  { scheme, path = `/link`, codeParam = `user_code` }: LinkConfig\n): string => {\n  if (scheme === undefined) throw new Error(`no custom scheme configured`);\n  const url = new URL(`${scheme}://${path.replace(/^\\//u, ``)}`);\n  url.searchParams.set(codeParam, userCode);\n  return url.toString();\n};\n\n/**\n * Parse an inbound link, however it arrived.\n *\n * One entry point for every route into the approval screen: an Expo\n * `Linking.getInitialURL()`, a PWA `launchQueue` target, or `location.href`.\n * Returning the `source` lets a host tell \"the OS routed this to us\" from \"the\n * user is on the web page\", which changes what the UI should offer.\n */\n/**\n * Read a code out of a path-style link (`/link/WDJB-MJHT`).\n *\n * A web URL needs a segment BEYOND the route itself. `/link` alone would\n * otherwise yield the code \"link\" — which the server rejects, so an ordinary\n * visit to the approval page reports itself as a failed code. That shipped\n * once: it showed \"that code is not valid\" on load and tore down the camera\n * that was mid-startup.\n *\n * A custom-scheme link has no route to strip — `hanko://WDJB-MJHT` carries the\n * code as its only segment — so one segment is enough there.\n */\nconst pathCode = (url: URL, isCustomScheme: boolean): string | undefined => {\n  const segments = url.pathname.split(`/`).filter(Boolean);\n  // `hanko://WDJB-MJHT` parses the code as the HOST, leaving no path at all.\n  if (isCustomScheme && segments.length === 0) {\n    return url.hostname.length > 0 ? url.hostname : undefined;\n  }\n  return segments.length >= (isCustomScheme ? 1 : 2)\n    ? segments[segments.length - 1]\n    : undefined;\n};\n\nexport const parseApprovalLink = (\n  href: string,\n  { codeParam = `user_code`, scheme }: Partial<LinkConfig> = {}\n): ParsedApprovalLink | null => {\n  let url: URL;\n  try {\n    url = new URL(href);\n  } catch {\n    return null;\n  }\n\n  const isCustomScheme = scheme !== undefined && url.protocol === `${scheme}:`;\n  if (\n    !isCustomScheme &&\n    url.protocol !== `https:` &&\n    url.protocol !== `http:`\n  ) {\n    return null;\n  }\n\n  const userCode =\n    url.searchParams.get(codeParam) ?? pathCode(url, isCustomScheme);\n\n  if (userCode === undefined || userCode.length === 0) return null;\n\n  return {\n    userCode,\n    href,\n    source: isCustomScheme ? `custom-scheme` : `web`\n  };\n};\n\n/**\n * Apple App Site Association, for `/.well-known/apple-app-site-association`.\n *\n * Serve as `application/json` over HTTPS with **no redirects** — Apple fetches\n * it directly and a redirect makes the association fail silently, which is the\n * single most common reason universal links \"just don't work\".\n *\n * @param appIds `<TEAM_ID>.<BUNDLE_ID>`, e.g. `QQ57RJ5UTD.gg.saeris.beerjournal`\n */\nexport const appleAppSiteAssociation = (\n  appIds: string[],\n  { paths = [`/link`, `/link/*`] }: { paths?: string[] } = {}\n): object => ({\n  applinks: {\n    // Required by the schema and must stay empty — Apple deprecated its use.\n    apps: [],\n    details: appIds.map((appID) => ({ appID, paths }))\n  }\n});\n\n/**\n * Digital Asset Links, for `/.well-known/assetlinks.json`.\n *\n * @param fingerprints SHA-256 of the app's SIGNING certificate. Note that Play\n *   App Signing re-signs the upload, so the fingerprint that works in\n *   production is the one from the Play Console — not your local keystore. A\n *   local-only fingerprint is why app links commonly work in debug and break\n *   after release.\n */\nexport const digitalAssetLinks = (\n  packageName: string,\n  fingerprints: string[]\n): object[] => [\n  {\n    relation: [`delegate_permission/common.handle_all_urls`],\n    target: {\n      namespace: `android_app`,\n      package_name: packageName,\n      sha256_cert_fingerprints: fingerprints\n    }\n  }\n];\n\n/**\n * Expo app config fragment for universal/app links.\n *\n * Merge into `app.json`. Requires a development or production build — the\n * entitlement is registered at build time, so **universal links do not work in\n * Expo Go**, and a project pinned to Expo Go must use the web fallback until it\n * moves to dev builds.\n */\nexport const expoLinkingConfig = ({\n  origin,\n  path = `/link`,\n  scheme\n}: LinkConfig): object => {\n  const { host } = new URL(origin);\n  return {\n    // Custom scheme, for the deliberate \"open in app\" tap.\n    ...(scheme === undefined ? {} : { scheme }),\n    ios: {\n      // No protocol, per Apple's format — including `https://` here is a\n      // silent misconfiguration.\n      associatedDomains: [`applinks:${host}`]\n    },\n    android: {\n      intentFilters: [\n        {\n          action: `VIEW`,\n          // `autoVerify` is what makes Android check assetlinks.json and open\n          // the app WITHOUT a chooser dialog. Without it the user gets a\n          // \"open with\" prompt every time, which reads as broken.\n          autoVerify: true,\n          data: [{ scheme: `https`, host, pathPrefix: path }],\n          category: [`BROWSABLE`, `DEFAULT`]\n        }\n      ]\n    }\n  };\n};\n\n/**\n * `launch_handler` fragment for a PWA manifest.\n *\n * `navigate-existing` so a scanned link reuses the already-open window rather\n * than stacking a second one. An approval screen that opened behind the window\n * the user was already looking at would appear not to have worked at all.\n *\n * Pair with `window.launchQueue.setConsumer()` to read the target URL — see\n * {@link consumeLaunchTarget}.\n */\nexport const pwaLaunchHandler = (): object => ({\n  launch_handler: { client_mode: `navigate-existing` }\n});\n\n/**\n * Read the URL an installed PWA was launched with.\n *\n * With `navigate-existing`, the window is reused and `location.href` may\n * already be correct — but when the app was cold-started or the consumer runs\n * before navigation settles, `launchQueue` is the only reliable source.\n *\n * Where `launchQueue` is unsupported — Safari and Firefox, as of 2026 — this\n * calls back with the current location ONLY when `fallbackToLocation` is set.\n * It defaults to false because the fallback cannot tell a launch from an\n * ordinary page load: it fires on every visit, and a caller that treats the\n * result as \"the user just arrived from a link\" will act on a URL nobody\n * followed. Opt in when the page is only ever reached by launch.\n */\nexport const consumeLaunchTarget = (\n  onTarget: (href: string) => void,\n  {\n    currentHref,\n    fallbackToLocation = false\n  }: { currentHref?: string; fallbackToLocation?: boolean } = {}\n): void => {\n  // Narrowed by runtime checks rather than a cast: neither `launchQueue` nor\n  // `location` exists on a server runtime, and `launchQueue` is absent in\n  // Safari and Firefox even in a browser.\n  const scope: Record<string, unknown> = globalThis;\n\n  const location = scope.location;\n  const currentLocationHref =\n    typeof location === `object` &&\n    location !== null &&\n    `href` in location &&\n    typeof location.href === `string`\n      ? location.href\n      : undefined;\n  const fallback = currentHref ?? currentLocationHref;\n\n  const queue = scope.launchQueue;\n  if (!isLaunchQueue(queue)) {\n    // Opt-in only. Firing here on every load would report an ordinary visit as\n    // a launch, and a caller acting on that URL acts on something nobody\n    // followed.\n    if (fallbackToLocation && fallback !== undefined) onTarget(fallback);\n    return;\n  }\n\n  queue.setConsumer(({ targetURL }) => {\n    const href = targetURL ?? fallback;\n    if (href !== undefined) onTarget(href);\n  });\n};\n\n/** The subset of `LaunchQueue` this module uses. */\ninterface LaunchQueueLike {\n  setConsumer: (fn: (params: { targetURL?: string }) => void) => void;\n}\n\n/**\n * Structural check for the Launch Handler API.\n *\n * A predicate rather than a cast: the API is absent on every server runtime and\n * in Safari and Firefox, so its presence is a runtime fact to test.\n */\nconst isLaunchQueue = (value: unknown): value is LaunchQueueLike =>\n  typeof value === `object` &&\n  value !== null &&\n  `setConsumer` in value &&\n  typeof value.setConsumer === `function`;\n"],"mappings":"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"}