@saeris/hanko 0.0.0 → 0.2.1

package/dist/server-BhoYRkCm.d.mts

@@ -0,0 +1,257 @@
+import { i as GrantState, r as GrantEvent } from "./machine-CRHKjtoP.mjs";
+import { a as DeviceGrantStore, i as DeviceGrant, n as DeviceAuthorizationError, r as DeviceAuthorizationResponse } from "./types-C82lb-zX.mjs";
+//#region src/codes.d.ts
+/**
+ * Code generation.
+ *
+ * Two codes with opposite constraints:
+ *
+ * - `user_code` is read off a TV across a room and typed on a phone, so it must
+ *   be SHORT. That caps its entropy, which is why RFC 8628 §5.1 requires the
+ *   server to rate-limit attempts — the code alone is not brute-force safe.
+ * - `device_code` is never displayed, so it has no usability ceiling. The spec
+ *   says "a very high entropy code SHOULD be used".
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628#section-5.1
+ */
+/**
+ * RFC 8628 §6.1's recommended base-20 alphabet: consonants only.
+ *
+ * No vowels, so generated codes cannot accidentally spell words. No digits, so
+ * there is no 0/O or 1/l/I confusion. 20^8 ≈ 34.5 bits at 8 characters, which
+ * the spec pairs with a 5-attempt rate limit.
+ */
+declare const BASE20_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ";
+/**
+ * Digits only — better for non-Latin locales and numeric TV remotes, which is
+ * why Plex-style flows often use them. Lower entropy per character than base-20
+ * (10 vs 20), so prefer a longer code when using this.
+ */
+declare const NUMERIC_ALPHABET = "0123456789";
+interface UserCodeOptions {
+  /** Significant characters, excluding any separator. Spec example uses 8. */
+  length?: number;
+  /** Character set to draw from. Defaults to {@link BASE20_ALPHABET}. */
+  alphabet?: string;
+  /**
+   * Inserted every `groupSize` characters purely for legibility.
+   * The stored/compared form never contains it — see {@link normalizeUserCode}.
+   */
+  separator?: string;
+  /** Characters per visual group. Ignored when `separator` is empty. */
+  groupSize?: number;
+}
+/**
+ * Generate a user-facing code, formatted for display.
+ *
+ * Defaults follow the spec's worked example: 8 base-20 characters shown as
+ * `WDJB-MJHT`.
+ */
+declare const generateUserCode: ({ length, alphabet, separator, groupSize }?: UserCodeOptions) => string;
+/**
+ * Canonicalize user input before comparison.
+ *
+ * RFC 8628 §6.1: the server strips punctuation it added for readability, and
+ * uppercases A-Z codes. Without this, a user typing `wdjb mjht` — which is what
+ * a phone keyboard will autocorrect toward — fails against `WDJB-MJHT` for no
+ * reason the user can see.
+ *
+ * Strips ALL non-alphanumerics, so it is agnostic to whichever separator the
+ * display format used.
+ */
+declare const normalizeUserCode: (input: string) => string;
+/**
+ * Generate a `device_code`: 256 bits, base64url, no padding.
+ *
+ * base64url (not base64) because this value travels in URLs and form bodies,
+ * where `+` and `/` would need escaping.
+ */
+declare const generateDeviceCode: () => string;
+//#endregion
+//#region src/grant.d.ts
+/** Observers of a grant's lifecycle. All optional, all fire after the move. */
+interface GrantHooks {
+  /** Any successful transition. */
+  onTransition?: (from: GrantState, to: GrantState, grant: DeviceGrant) => void;
+  /** The user authorized. `subject` is whoever they are to the host app. */
+  onApproved?: (subject: string, grant: DeviceGrant) => void;
+  /** The user refused. */
+  onDenied?: (grant: DeviceGrant) => void;
+  /** The deadline passed without a decision, or before redemption. */
+  onExpired?: (grant: DeviceGrant) => void;
+  /** The device redeemed its approval. Terminal. */
+  onRedeemed?: (subject: string, grant: DeviceGrant) => void;
+  /**
+   * An event the current state does not accept.
+   *
+   * Not an error — a device polling twice in a row legitimately produces one —
+   * but worth surfacing, since a burst of them means a confused caller.
+   */
+  onRejected?: (state: GrantState, event: GrantEvent[`type`]) => void;
+}
+declare class Grant {
+  #private;
+  constructor(grant: DeviceGrant, hooks?: GrantHooks);
+  /** Rehydrate from a store record. */
+  static from(grant: DeviceGrant, hooks?: GrantHooks): Grant;
+  get state(): GrantState;
+  get userCode(): string;
+  get interval(): number;
+  get settled(): boolean;
+  /**
+   * 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(): string;
+  /** Whether this grant's deadline has passed as of `now`. */
+  expired(now: number): boolean;
+  /**
+   * 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: number): boolean;
+  /** Record that a poll happened, without changing state. */
+  markPolled(now: number): void;
+  /**
+   * 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: number): number;
+  /**
+   * 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: GrantEvent): boolean;
+  /**
+   * 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(): DeviceGrant;
+}
+//#endregion
+//#region src/server.d.ts
+interface HankoServerOptions {
+  /** Where grants live. Use `MemoryDeviceGrantStore` for dev. */
+  store: DeviceGrantStore;
+  /**
+   * Absolute URL the user visits to approve, e.g. `https://example.com/link`.
+   * Shown on the device verbatim, so keep it short and typeable.
+   */
+  verificationUri: string;
+  /**
+   * Builds the QR target. Defaults to `${verificationUri}?user_code=${code}`.
+   * Override if your approval page reads the code from a path segment.
+   */
+  buildVerificationUriComplete?: (userCode: string, verificationUri: string) => string;
+  /** Code lifetime in seconds. Default 900 (15 min). */
+  expiresInSeconds?: number;
+  /** Starting poll interval in seconds. Spec default 5. */
+  intervalSeconds?: number;
+  /** Shape of the user code. See {@link UserCodeOptions}. */
+  userCode?: UserCodeOptions;
+  /** Injectable clock. Tests pass a fake; production leaves it alone. */
+  now?: () => number;
+  /**
+   * Lifecycle observers, applied to every grant this server handles.
+   *
+   * The integration seam for host frameworks: persist to a second store, emit
+   * telemetry, push to a websocket. Hooks observe; they cannot force a
+   * transition.
+   */
+  hooks?: GrantHooks;
+}
+/** Discriminated result of a poll. Callers switch on `status`. */
+type PollResult = {
+  status: `pending`;
+  error: Extract<DeviceAuthorizationError, `authorization_pending`>;
+} | {
+  status: `slow_down`;
+  error: Extract<DeviceAuthorizationError, `slow_down`>;
+  interval: number;
+} | {
+  status: `denied`;
+  error: Extract<DeviceAuthorizationError, `access_denied`>;
+} | {
+  status: `expired`;
+  error: Extract<DeviceAuthorizationError, `expired_token`>;
+} | {
+  status: `approved`;
+  subject: string;
+};
+interface ApproveResult {
+  ok: boolean;
+  /** Present when `ok` is false. Lets callers show a precise message. */
+  reason?: `not_found` | `expired` | `already_resolved`;
+  grant?: DeviceGrant;
+}
+declare class HankoServer {
+  #private;
+  constructor({ store, verificationUri, buildVerificationUriComplete, expiresInSeconds, intervalSeconds, userCode, now, hooks }: HankoServerOptions);
+  /**
+   * 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.
+   */
+  requestAuthorization({ clientId, scope, verificationUri }?: {
+    clientId?: string;
+    scope?: string;
+    /**
+     * Override the configured verification URI for this grant.
+     *
+     * One deployment is commonly reachable through several hostnames — a
+     * preview URL, a custom domain, a tunnel — and the QR has to encode the one
+     * the device is actually talking to. Derive it from the incoming request
+     * (`x-forwarded-host` behind a proxy) and the code always points somewhere
+     * reachable, with no redeploy when the hostname changes.
+     */
+    verificationUri?: string;
+  }): Promise<DeviceAuthorizationResponse>;
+  /**
+   * 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.
+   */
+  poll(deviceCode: string): Promise<PollResult>;
+  /**
+   * 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.
+   */
+  lookupByUserCode(input: string): Promise<DeviceGrant | null>;
+  /** Record approval. `subject` is opaque to hanko; it is echoed back on poll. */
+  approve(input: string, subject: string): Promise<ApproveResult>;
+  /** Record denial, so the device can stop polling and say why. */
+  deny(input: string): Promise<ApproveResult>;
+}
+/**
+ * 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.
+ */
+declare const createHankoServer: (options: HankoServerOptions) => HankoServer;
+//#endregion
+export { createHankoServer as a, BASE20_ALPHABET as c, generateDeviceCode as d, generateUserCode as f, PollResult as i, NUMERIC_ALPHABET as l, HankoServer as n, Grant as o, normalizeUserCode as p, HankoServerOptions as r, GrantHooks as s, ApproveResult as t, UserCodeOptions as u };
+//# sourceMappingURL=server-BhoYRkCm.d.mts.map

package/dist/server-BhoYRkCm.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-BhoYRkCm.d.mts","names":[],"sources":["../src/codes.ts","../src/grant.ts","../src/server.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;cAqBa;;;;;;cAOA;UAwBI;;EAEf;;EAEA;;;;;EAKA;;EAEA;;;;;;;;cASW,qBAAoB,QAAA,UAAA,WAAA,cAK9B;;;;;;;;;;;;cA4BU,oBAAqB;;;;;;;cASrB;;;;UC5FI;;EAEf,gBAAgB,MAAM,YAAY,IAAI,YAAY,OAAO;;EAEzD,cAAc,iBAAiB,OAAO;;EAEtC,YAAY,OAAO;;EAEnB,aAAa,OAAO;;EAEpB,cAAc,iBAAiB,OAAO;;;;;;;EAOtC,cAAc,OAAO,YAAY,OAAO;;cAG7B;;EAaC,YAAA,OAAO,aAAa,QAAO;;SAchC,KAAK,OAAO,aAAa,QAAQ,aAAa;MAIjD,SAAS;MAIT;MAIA;MAIA;;;;;;;;MAWA;;EAUJ,QAAQ;;;;;;;;EAWR,eAAe;;EAQf,WAAW;;;;;;;;EAWX,SAAS;;;;;;;;EAaT,KAAK,OAAO;;;;;;;;EA0CZ,UAAU;;;;UC/JK;;EAEf,OAAO;;;;;EAKP;;;;;EAKA,gCACE,kBACA;;EAGF;;EAEA;;EAEA,WAAW;;EAEX;;;;;;;;EAQA,QAAQ;;;KAIE;EAEN;EACA,OAAO,QAAQ;;EAGf;EACA,OAAO,QAAQ;EACf;;EAGA;EACA,OAAO,QAAQ;;EAGf;EACA,OAAO,QAAQ;;EAEf;EAAoB;;UAET;EACf;;EAEA;EACA,QAAQ;;cAGG;;EAaC,cACV,OACA,iBACA,8BAEA,kBACA,iBACA,UACA,KACA,SACC;;;;;;;EAuCG,uBACJ,UACA,OACA;IAEA;IACA;;;;;;;;;;IAUA;MACO,QAAQ;;;;;;;;;EAqCX,KAAK,qBAAqB,QAAQ;;;;;;;;;EA+ClC,iBAAiB,gBAAgB,QAAQ;;EAQzC,QAAQ,eAAe,kBAAkB,QAAQ;;EAKjD,KAAK,gBAAgB,QAAQ;;;;;;;;cA6CxB,oBAAqB,SAAS,uBAAqB"}

package/dist/stores/kv.d.mts

@@ -0,0 +1,64 @@
+import { a as DeviceGrantStore, i as DeviceGrant } from "../types-C82lb-zX.mjs";
+//#region src/stores/kv.d.ts
+/** What hanko needs from a KV service. */
+interface KeyValueAdapter {
+  get(key: string): Promise<string | null>;
+  /** `ttlSeconds` is a hint; stores without TTL may ignore it (see below). */
+  set(key: string, value: string, ttlSeconds: number): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+interface KvDeviceGrantStoreOptions {
+  kv: KeyValueAdapter;
+  /** Namespace, so grants cannot collide with the host app's own keys. */
+  prefix?: string;
+  /**
+   * Extra seconds to keep a grant past its own deadline.
+   *
+   * Without this, a grant vanishes at the instant it expires and the device's
+   * next poll gets "unknown code" — indistinguishable from a typo. The grace
+   * window lets the server answer `expired_token` honestly, which is what a
+   * client needs to stop cleanly rather than retry.
+   */
+  graceSeconds?: number;
+  now?: () => number;
+}
+/**
+ * Two keys per grant: `device:<code>` holds the record, `user:<code>` points at
+ * it.
+ *
+ * A pointer rather than a duplicate, because the record changes on every poll
+ * and two copies would diverge — the device would see a raised interval the
+ * approval page did not.
+ */
+declare class KvDeviceGrantStore implements DeviceGrantStore {
+  #private;
+  constructor({ kv, prefix, graceSeconds, now }: KvDeviceGrantStoreOptions);
+  create(grant: DeviceGrant): Promise<void>;
+  findByDeviceCode(deviceCode: string): Promise<DeviceGrant | null>;
+  findByUserCode(userCode: string): Promise<DeviceGrant | null>;
+  update(grant: DeviceGrant): Promise<void>;
+  /**
+   * No-op: TTL is the pruning mechanism.
+   *
+   * Present so the interface is satisfied without a scan. Sweeping a KV store
+   * for expired keys would cost a list operation per request to do worse than
+   * what the service already does for free.
+   */
+  prune(): void;
+}
+/**
+ * Adapter for a KV service whose `set` takes options rather than a TTL number.
+ *
+ * Covers Workers KV (`{ expirationTtl }`) and Vercel KV (`{ ex }`) without
+ * either needing its own class.
+ */
+declare const kvFromOptionsApi: ({ get, set, remove, ttlKey }: {
+  get: (key: string) => Promise<string | null>;
+  set: (key: string, value: string, options: Record<string, number>) => Promise<void>;
+  remove: (key: string) => Promise<void>;
+  /** Option name carrying the TTL. `expirationTtl` for Workers KV, `ex` for Redis. */
+  ttlKey?: string;
+}) => KeyValueAdapter;
+//#endregion
+export { KeyValueAdapter, KvDeviceGrantStore, KvDeviceGrantStoreOptions, kvFromOptionsApi };
+//# sourceMappingURL=kv.d.mts.map

package/dist/stores/kv.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.mts","names":[],"sources":["../../src/stores/kv.ts"],"mappings":";;;UAgBiB;EACf,IAAI,cAAc;;EAElB,IAAI,aAAa,eAAe,qBAAqB;EACrD,OAAO,cAAc;;UAGN;EACf,IAAI;;EAEJ;;;;;;;;;EASA;EACA;;;;;;;;;;cAWW,8BAA8B;;EAM7B,cACV,IACA,QACA,cACA,OACC;EAqBG,OAAO,OAAO,cAAc;EAU5B,iBAAiB,qBAAqB,QAAQ;EAiB9C,eAAe,mBAAmB,QAAQ;EAK1C,OAAO,OAAO,cAAc;;;;;;;;EAqBlC;;;;;;;;cAWW,qBAAoB,KAAA,KAAA,QAAA;EAM/B,MAAM,gBAAgB;EACtB,MACE,aACA,eACA,SAAS,2BACN;EACL,SAAS,gBAAgB;;EAEzB;MACE"}

package/dist/stores/kv.mjs

@@ -0,0 +1,87 @@
+//#region src/stores/kv.ts
+/**
+* Two keys per grant: `device:<code>` holds the record, `user:<code>` points at
+* it.
+*
+* A pointer rather than a duplicate, because the record changes on every poll
+* and two copies would diverge — the device would see a raised interval the
+* approval page did not.
+*/
+var KvDeviceGrantStore = class {
+	#kv;
+	#prefix;
+	#graceSeconds;
+	#now;
+	constructor({ kv, prefix = `hanko`, graceSeconds = 60, now = () => Date.now() }) {
+		this.#kv = kv;
+		this.#prefix = prefix;
+		this.#graceSeconds = graceSeconds;
+		this.#now = now;
+	}
+	#deviceKey(code) {
+		return `${this.#prefix}:device:${code}`;
+	}
+	#userKey(code) {
+		return `${this.#prefix}:user:${code}`;
+	}
+	/** Seconds until this grant may be dropped. At least 1 — never 0 or negative. */
+	#ttl(grant) {
+		const remaining = Math.ceil((grant.expiresAt - this.#now()) / 1e3);
+		return Math.max(1, remaining + this.#graceSeconds);
+	}
+	async create(grant) {
+		const ttl = this.#ttl(grant);
+		await this.#kv.set(this.#deviceKey(grant.device_code), JSON.stringify(grant), ttl);
+		await this.#kv.set(this.#userKey(grant.user_code), grant.device_code, ttl);
+	}
+	async findByDeviceCode(deviceCode) {
+		const raw = await this.#kv.get(this.#deviceKey(deviceCode));
+		if (raw === null) return null;
+		try {
+			const parsed = JSON.parse(raw);
+			return isDeviceGrant(parsed) ? parsed : null;
+		} catch {
+			return null;
+		}
+	}
+	async findByUserCode(userCode) {
+		const deviceCode = await this.#kv.get(this.#userKey(userCode));
+		return deviceCode === null ? null : this.findByDeviceCode(deviceCode);
+	}
+	async update(grant) {
+		await this.#kv.set(this.#deviceKey(grant.device_code), JSON.stringify(grant), this.#ttl(grant));
+	}
+	/**
+	* No-op: TTL is the pruning mechanism.
+	*
+	* Present so the interface is satisfied without a scan. Sweeping a KV store
+	* for expired keys would cost a list operation per request to do worse than
+	* what the service already does for free.
+	*/
+	prune() {}
+};
+/**
+* Adapter for a KV service whose `set` takes options rather than a TTL number.
+*
+* Covers Workers KV (`{ expirationTtl }`) and Vercel KV (`{ ex }`) without
+* either needing its own class.
+*/
+const kvFromOptionsApi = ({ get, set, remove, ttlKey = `expirationTtl` }) => ({
+	get,
+	set: async (key, value, ttlSeconds) => {
+		await set(key, value, { [ttlKey]: ttlSeconds });
+	},
+	delete: remove
+});
+/**
+* Structural check for a stored grant.
+*
+* Only the fields the machine cannot run without. Optional ones are left
+* unchecked — a missing `scope` costs a label on the approval screen, while a
+* missing `status` would put the state machine in an undefined state.
+*/
+const isDeviceGrant = (value) => typeof value === `object` && value !== null && `device_code` in value && typeof value.device_code === `string` && `user_code` in value && typeof value.user_code === `string` && `status` in value && typeof value.status === `string` && `expiresAt` in value && typeof value.expiresAt === `number` && `interval` in value && typeof value.interval === `number`;
+//#endregion
+export { KvDeviceGrantStore, kvFromOptionsApi };
+
+//# sourceMappingURL=kv.mjs.map

package/dist/stores/kv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.mjs","names":["#kv","#prefix","#graceSeconds","#now","#ttl","#deviceKey","#userKey"],"sources":["../../src/stores/kv.ts"],"sourcesContent":["/**\n * Grant store over any TTL-capable key-value service.\n *\n * The shape Upstash Redis, Cloudflare Workers KV, Deno KV, Vercel KV, and\n * plain `ioredis` all satisfy — three methods, one of which takes a TTL. That\n * is deliberately the lowest common denominator, so an adapter is a few lines\n * rather than a package.\n *\n * Suits stateless edge functions specifically: nothing is cached in the\n * instance, so a flow survives its requests landing on different workers, and\n * TTL expiry means abandoned grants cost nothing to clean up.\n */\n\nimport type { DeviceGrant, DeviceGrantStore } from \"../types.js\";\n\n/** What hanko needs from a KV service. */\nexport interface KeyValueAdapter {\n  get(key: string): Promise<string | null>;\n  /** `ttlSeconds` is a hint; stores without TTL may ignore it (see below). */\n  set(key: string, value: string, ttlSeconds: number): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\nexport interface KvDeviceGrantStoreOptions {\n  kv: KeyValueAdapter;\n  /** Namespace, so grants cannot collide with the host app's own keys. */\n  prefix?: string;\n  /**\n   * Extra seconds to keep a grant past its own deadline.\n   *\n   * Without this, a grant vanishes at the instant it expires and the device's\n   * next poll gets \"unknown code\" — indistinguishable from a typo. The grace\n   * window lets the server answer `expired_token` honestly, which is what a\n   * client needs to stop cleanly rather than retry.\n   */\n  graceSeconds?: number;\n  now?: () => number;\n}\n\n/**\n * Two keys per grant: `device:<code>` holds the record, `user:<code>` points at\n * it.\n *\n * A pointer rather than a duplicate, because the record changes on every poll\n * and two copies would diverge — the device would see a raised interval the\n * approval page did not.\n */\nexport class KvDeviceGrantStore implements DeviceGrantStore {\n  readonly #kv: KeyValueAdapter;\n  readonly #prefix: string;\n  readonly #graceSeconds: number;\n  readonly #now: () => number;\n\n  constructor({\n    kv,\n    prefix = `hanko`,\n    graceSeconds = 60,\n    now = (): number => Date.now()\n  }: KvDeviceGrantStoreOptions) {\n    this.#kv = kv;\n    this.#prefix = prefix;\n    this.#graceSeconds = graceSeconds;\n    this.#now = now;\n  }\n\n  #deviceKey(code: string): string {\n    return `${this.#prefix}:device:${code}`;\n  }\n\n  #userKey(code: string): string {\n    return `${this.#prefix}:user:${code}`;\n  }\n\n  /** Seconds until this grant may be dropped. At least 1 — never 0 or negative. */\n  #ttl(grant: DeviceGrant): number {\n    const remaining = Math.ceil((grant.expiresAt - this.#now()) / 1000);\n    return Math.max(1, remaining + this.#graceSeconds);\n  }\n\n  async create(grant: DeviceGrant): Promise<void> {\n    const ttl = this.#ttl(grant);\n    await this.#kv.set(\n      this.#deviceKey(grant.device_code),\n      JSON.stringify(grant),\n      ttl\n    );\n    await this.#kv.set(this.#userKey(grant.user_code), grant.device_code, ttl);\n  }\n\n  async findByDeviceCode(deviceCode: string): Promise<DeviceGrant | null> {\n    const raw = await this.#kv.get(this.#deviceKey(deviceCode));\n    if (raw === null) return null;\n    try {\n      const parsed: unknown = JSON.parse(raw);\n      // Validated rather than asserted: this value came back from a shared\n      // store that another deploy — or an older version of this library — may\n      // have written. A half-shaped record would fail deep inside the machine\n      // instead of here.\n      return isDeviceGrant(parsed) ? parsed : null;\n    } catch {\n      // A corrupt value is not a live grant. Returning null lets the caller\n      // report `expired_token` rather than crashing an edge function.\n      return null;\n    }\n  }\n\n  async findByUserCode(userCode: string): Promise<DeviceGrant | null> {\n    const deviceCode = await this.#kv.get(this.#userKey(userCode));\n    return deviceCode === null ? null : this.findByDeviceCode(deviceCode);\n  }\n\n  async update(grant: DeviceGrant): Promise<void> {\n    // Rewrites the TTL on every update, which keeps the key alive exactly as\n    // long as the grant's own deadline says — not as long as the last write\n    // happened to leave it.\n    await this.#kv.set(\n      this.#deviceKey(grant.device_code),\n      JSON.stringify(grant),\n      this.#ttl(grant)\n    );\n  }\n\n  /**\n   * No-op: TTL is the pruning mechanism.\n   *\n   * Present so the interface is satisfied without a scan. Sweeping a KV store\n   * for expired keys would cost a list operation per request to do worse than\n   * what the service already does for free.\n   */\n  // Must stay an instance method to satisfy `DeviceGrantStore`; making it\n  // static would take it off the interface.\n  // oxlint-disable-next-line eslint/class-methods-use-this\n  prune(): void {\n    // Intentionally empty.\n  }\n}\n\n/**\n * Adapter for a KV service whose `set` takes options rather than a TTL number.\n *\n * Covers Workers KV (`{ expirationTtl }`) and Vercel KV (`{ ex }`) without\n * either needing its own class.\n */\nexport const kvFromOptionsApi = ({\n  get,\n  set,\n  remove,\n  ttlKey = `expirationTtl`\n}: {\n  get: (key: string) => Promise<string | null>;\n  set: (\n    key: string,\n    value: string,\n    options: Record<string, number>\n  ) => Promise<void>;\n  remove: (key: string) => Promise<void>;\n  /** Option name carrying the TTL. `expirationTtl` for Workers KV, `ex` for Redis. */\n  ttlKey?: string;\n}): KeyValueAdapter => ({\n  get,\n  set: async (key, value, ttlSeconds) => {\n    await set(key, value, { [ttlKey]: ttlSeconds });\n  },\n  delete: remove\n});\n\n/**\n * Structural check for a stored grant.\n *\n * Only the fields the machine cannot run without. Optional ones are left\n * unchecked — a missing `scope` costs a label on the approval screen, while a\n * missing `status` would put the state machine in an undefined state.\n */\nconst isDeviceGrant = (value: unknown): value is DeviceGrant =>\n  typeof value === `object` &&\n  value !== null &&\n  `device_code` in value &&\n  typeof value.device_code === `string` &&\n  `user_code` in value &&\n  typeof value.user_code === `string` &&\n  `status` in value &&\n  typeof value.status === `string` &&\n  `expiresAt` in value &&\n  typeof value.expiresAt === `number` &&\n  `interval` in value &&\n  typeof value.interval === `number`;\n"],"mappings":";;;;;;;;;AA+CA,IAAa,qBAAb,MAA4D;CAC1D;CACA;CACA;CACA;CAEA,YAAY,EACV,IACA,SAAS,SACT,eAAe,IACf,YAAoB,KAAK,IAAI,KACD;EAC5B,KAAKA,MAAM;EACX,KAAKC,UAAU;EACf,KAAKC,gBAAgB;EACrB,KAAKC,OAAO;CACd;CAEA,WAAW,MAAsB;EAC/B,OAAO,GAAG,KAAKF,QAAQ,UAAU;CACnC;CAEA,SAAS,MAAsB;EAC7B,OAAO,GAAG,KAAKA,QAAQ,QAAQ;CACjC;;CAGA,KAAK,OAA4B;EAC/B,MAAM,YAAY,KAAK,MAAM,MAAM,YAAY,KAAKE,KAAK,KAAK,GAAI;EAClE,OAAO,KAAK,IAAI,GAAG,YAAY,KAAKD,aAAa;CACnD;CAEA,MAAM,OAAO,OAAmC;EAC9C,MAAM,MAAM,KAAKE,KAAK,KAAK;EAC3B,MAAM,KAAKJ,IAAI,IACb,KAAKK,WAAW,MAAM,WAAW,GACjC,KAAK,UAAU,KAAK,GACpB,GACF;EACA,MAAM,KAAKL,IAAI,IAAI,KAAKM,SAAS,MAAM,SAAS,GAAG,MAAM,aAAa,GAAG;CAC3E;CAEA,MAAM,iBAAiB,YAAiD;EACtE,MAAM,MAAM,MAAM,KAAKN,IAAI,IAAI,KAAKK,WAAW,UAAU,CAAC;EAC1D,IAAI,QAAQ,MAAM,OAAO;EACzB,IAAI;GACF,MAAM,SAAkB,KAAK,MAAM,GAAG;GAKtC,OAAO,cAAc,MAAM,IAAI,SAAS;EAC1C,QAAQ;GAGN,OAAO;EACT;CACF;CAEA,MAAM,eAAe,UAA+C;EAClE,MAAM,aAAa,MAAM,KAAKL,IAAI,IAAI,KAAKM,SAAS,QAAQ,CAAC;EAC7D,OAAO,eAAe,OAAO,OAAO,KAAK,iBAAiB,UAAU;CACtE;CAEA,MAAM,OAAO,OAAmC;EAI9C,MAAM,KAAKN,IAAI,IACb,KAAKK,WAAW,MAAM,WAAW,GACjC,KAAK,UAAU,KAAK,GACpB,KAAKD,KAAK,KAAK,CACjB;CACF;;;;;;;;CAYA,QAAc,CAEd;AACF;;;;;;;AAQA,MAAa,oBAAoB,EAC/B,KACA,KACA,QACA,SAAS,uBAWa;CACtB;CACA,KAAK,OAAO,KAAK,OAAO,eAAe;EACrC,MAAM,IAAI,KAAK,OAAO,GAAG,SAAS,WAAW,CAAC;CAChD;CACA,QAAQ;AACV;;;;;;;;AASA,MAAM,iBAAiB,UACrB,OAAO,UAAU,YACjB,UAAU,QACV,iBAAiB,SACjB,OAAO,MAAM,gBAAgB,YAC7B,eAAe,SACf,OAAO,MAAM,cAAc,YAC3B,YAAY,SACZ,OAAO,MAAM,WAAW,YACxB,eAAe,SACf,OAAO,MAAM,cAAc,YAC3B,cAAc,SACd,OAAO,MAAM,aAAa"}

package/dist/stores/memory.d.mts

@@ -0,0 +1,22 @@
+import { a as DeviceGrantStore, i as DeviceGrant } from "../types-C82lb-zX.mjs";
+//#region src/stores/memory.d.ts
+declare class MemoryDeviceGrantStore implements DeviceGrantStore {
+  #private;
+  create(grant: DeviceGrant): void;
+  findByDeviceCode(deviceCode: string): DeviceGrant | null;
+  findByUserCode(userCode: string): DeviceGrant | null;
+  update(grant: DeviceGrant): void;
+  /**
+   * Drop grants past their deadline.
+   *
+   * Without this the maps grow without bound in a long-lived dev server. Both
+   * indexes must be cleared together or the user_code index leaks entries
+   * pointing at deleted grants.
+   */
+  prune(now: number): void;
+  /** Test affordance: current grant count. */
+  get size(): number;
+}
+//#endregion
+export { MemoryDeviceGrantStore };
+//# sourceMappingURL=memory.d.mts.map

package/dist/stores/memory.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../src/stores/memory.ts"],"mappings":";;cAWa,kCAAkC;;EAM7C,OAAO,OAAO;EAKd,iBAAiB,qBAAqB;EAItC,eAAe,mBAAmB;EAKlC,OAAO,OAAO;;;;;;;;EAWd,MAAM;;MAUF"}

package/dist/stores/memory.mjs

@@ -0,0 +1,42 @@
+//#region src/stores/memory.ts
+var MemoryDeviceGrantStore = class {
+	/** Keyed by device_code. */
+	#byDeviceCode = /* @__PURE__ */ new Map();
+	/** user_code → device_code. Avoids scanning on the user-facing lookup. */
+	#userCodeIndex = /* @__PURE__ */ new Map();
+	create(grant) {
+		this.#byDeviceCode.set(grant.device_code, grant);
+		this.#userCodeIndex.set(grant.user_code, grant.device_code);
+	}
+	findByDeviceCode(deviceCode) {
+		return this.#byDeviceCode.get(deviceCode) ?? null;
+	}
+	findByUserCode(userCode) {
+		const deviceCode = this.#userCodeIndex.get(userCode);
+		return deviceCode === void 0 ? null : this.findByDeviceCode(deviceCode);
+	}
+	update(grant) {
+		this.#byDeviceCode.set(grant.device_code, grant);
+	}
+	/**
+	* Drop grants past their deadline.
+	*
+	* Without this the maps grow without bound in a long-lived dev server. Both
+	* indexes must be cleared together or the user_code index leaks entries
+	* pointing at deleted grants.
+	*/
+	prune(now) {
+		for (const [deviceCode, grant] of this.#byDeviceCode) if (now >= grant.expiresAt) {
+			this.#byDeviceCode.delete(deviceCode);
+			this.#userCodeIndex.delete(grant.user_code);
+		}
+	}
+	/** Test affordance: current grant count. */
+	get size() {
+		return this.#byDeviceCode.size;
+	}
+};
+//#endregion
+export { MemoryDeviceGrantStore };
+
+//# sourceMappingURL=memory.mjs.map

package/dist/stores/memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.mjs","names":["#byDeviceCode","#userCodeIndex"],"sources":["../../src/stores/memory.ts"],"sourcesContent":["/**\n * In-memory grant store — development and tests only.\n *\n * State dies with the process and is not shared across instances, so this is\n * wrong for any deployment with more than one worker. It exists so the library\n * is runnable with zero infrastructure; real deployments supply a Redis /\n * Postgres / Durable Object adapter against the same interface.\n */\n\nimport type { DeviceGrant, DeviceGrantStore } from \"../types.js\";\n\nexport class MemoryDeviceGrantStore implements DeviceGrantStore {\n  /** Keyed by device_code. */\n  readonly #byDeviceCode = new Map<string, DeviceGrant>();\n  /** user_code → device_code. Avoids scanning on the user-facing lookup. */\n  readonly #userCodeIndex = new Map<string, string>();\n\n  create(grant: DeviceGrant): void {\n    this.#byDeviceCode.set(grant.device_code, grant);\n    this.#userCodeIndex.set(grant.user_code, grant.device_code);\n  }\n\n  findByDeviceCode(deviceCode: string): DeviceGrant | null {\n    return this.#byDeviceCode.get(deviceCode) ?? null;\n  }\n\n  findByUserCode(userCode: string): DeviceGrant | null {\n    const deviceCode = this.#userCodeIndex.get(userCode);\n    return deviceCode === undefined ? null : this.findByDeviceCode(deviceCode);\n  }\n\n  update(grant: DeviceGrant): void {\n    this.#byDeviceCode.set(grant.device_code, grant);\n  }\n\n  /**\n   * Drop grants past their deadline.\n   *\n   * Without this the maps grow without bound in a long-lived dev server. Both\n   * indexes must be cleared together or the user_code index leaks entries\n   * pointing at deleted grants.\n   */\n  prune(now: number): void {\n    for (const [deviceCode, grant] of this.#byDeviceCode) {\n      if (now >= grant.expiresAt) {\n        this.#byDeviceCode.delete(deviceCode);\n        this.#userCodeIndex.delete(grant.user_code);\n      }\n    }\n  }\n\n  /** Test affordance: current grant count. */\n  get size(): number {\n    return this.#byDeviceCode.size;\n  }\n}\n"],"mappings":";AAWA,IAAa,yBAAb,MAAgE;;CAE9D,gCAAyB,IAAI,IAAyB;;CAEtD,iCAA0B,IAAI,IAAoB;CAElD,OAAO,OAA0B;EAC/B,KAAKA,cAAc,IAAI,MAAM,aAAa,KAAK;EAC/C,KAAKC,eAAe,IAAI,MAAM,WAAW,MAAM,WAAW;CAC5D;CAEA,iBAAiB,YAAwC;EACvD,OAAO,KAAKD,cAAc,IAAI,UAAU,KAAK;CAC/C;CAEA,eAAe,UAAsC;EACnD,MAAM,aAAa,KAAKC,eAAe,IAAI,QAAQ;EACnD,OAAO,eAAe,KAAA,IAAY,OAAO,KAAK,iBAAiB,UAAU;CAC3E;CAEA,OAAO,OAA0B;EAC/B,KAAKD,cAAc,IAAI,MAAM,aAAa,KAAK;CACjD;;;;;;;;CASA,MAAM,KAAmB;EACvB,KAAK,MAAM,CAAC,YAAY,UAAU,KAAKA,eACrC,IAAI,OAAO,MAAM,WAAW;GAC1B,KAAKA,cAAc,OAAO,UAAU;GACpC,KAAKC,eAAe,OAAO,MAAM,SAAS;EAC5C;CAEJ;;CAGA,IAAI,OAAe;EACjB,OAAO,KAAKD,cAAc;CAC5B;AACF"}

package/dist/types-BvBIFPH6.mjs

@@ -0,0 +1,7 @@
+//#region src/types.ts
+/** The grant type URN. Sent verbatim as `grant_type`. */
+const DEVICE_CODE_GRANT_TYPE = `urn:ietf:params:oauth:grant-type:device_code`;
+//#endregion
+export { DEVICE_CODE_GRANT_TYPE as t };
+
+//# sourceMappingURL=types-BvBIFPH6.mjs.map

package/dist/types-BvBIFPH6.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-BvBIFPH6.mjs","names":[],"sources":["../src/types.ts"],"sourcesContent":["/**\n * Wire types for the OAuth 2.0 Device Authorization Grant (RFC 8628).\n *\n * Field names are the spec's, not ours — they cross the network to clients we\n * do not control, so they are forever-identifiers. Do not rename them to fit\n * local style.\n *\n * @see https://datatracker.ietf.org/doc/html/rfc8628\n */\n\nimport type { GrantState } from \"./machine.js\";\n\n/** RFC 8628 §3.2 — device authorization response. */\nexport interface DeviceAuthorizationResponse {\n  /** High-entropy secret the device polls with. Never shown to the user. */\n  device_code: string;\n  /** Short code the user reads off the screen and types (or verifies). */\n  user_code: string;\n  /** Where the user goes to authorize. */\n  verification_uri: string;\n  /**\n   * `verification_uri` with the `user_code` embedded, for QR/NFC.\n   * OPTIONAL in the spec; we always emit it because the QR path is the point.\n   */\n  verification_uri_complete?: string;\n  /** Lifetime in seconds of BOTH codes. */\n  expires_in: number;\n  /** Minimum seconds between polls. Spec default is 5. */\n  interval: number;\n}\n\n/** RFC 8628 §3.5 — token endpoint error codes for this grant. */\nexport type DeviceAuthorizationError =\n  /** Keep polling; the user has not finished yet. */\n  | `authorization_pending`\n  /** Keep polling, but permanently add 5s to the interval. */\n  | `slow_down`\n  /** Stop. The user said no. */\n  | `access_denied`\n  /** Stop. The codes aged out. */\n  | `expired_token`;\n\n/** The grant type URN. Sent verbatim as `grant_type`. */\nexport const DEVICE_CODE_GRANT_TYPE =\n  `urn:ietf:params:oauth:grant-type:device_code` as const;\n\n/**\n * Lifecycle of one authorization attempt.\n *\n * Aliased from `machine.ts`, which owns the states and the legal transitions\n * between them. Kept under its record-field name so a store adapter can type\n * its status column without importing the machine.\n */\nexport type GrantStatus = GrantState;\n\n/**\n * A stored authorization attempt.\n *\n * `subject` is whatever the host app uses to identify the approving user (a\n * DID, a user id, a session id). hanko never interprets it — it only carries it\n * from the approving device back to the polling device.\n */\nexport interface DeviceGrant {\n  device_code: string;\n  user_code: string;\n  status: GrantStatus;\n  /** Epoch ms. Compared against an injected clock, never `Date.now()` directly. */\n  expiresAt: number;\n  /** Seconds. Mutable: `slow_down` raises it. */\n  interval: number;\n  /** OAuth client that started the flow, if the host app tracks clients. */\n  clientId?: string;\n  /** Requested scopes, uninterpreted. */\n  scope?: string;\n  /** Set when status becomes `approved`. */\n  subject?: string;\n  /** Epoch ms of the last poll, for `slow_down` enforcement. */\n  lastPolledAt?: number;\n}\n\n/**\n * Persistence boundary.\n *\n * Deliberately tiny so adapters (Redis, Supabase, Better-Auth, Durable Objects)\n * are trivial. All methods may be async. Lookup by BOTH codes is required: the\n * device polls by `device_code`, the user approves by `user_code`.\n */\nexport interface DeviceGrantStore {\n  create(grant: DeviceGrant): Promise<void> | void;\n  findByDeviceCode(\n    deviceCode: string\n  ): Promise<DeviceGrant | null> | DeviceGrant | null;\n  findByUserCode(\n    userCode: string\n  ): Promise<DeviceGrant | null> | DeviceGrant | null;\n  update(grant: DeviceGrant): Promise<void> | void;\n  /** Drop expired grants. Called opportunistically; may be a no-op with TTL stores. */\n  prune?(now: number): Promise<void> | void;\n}\n"],"mappings":";;AA2CA,MAAa,yBACX"}

package/dist/types-C82lb-zX.d.mts

@@ -0,0 +1,82 @@
+import { i as GrantState } from "./machine-CRHKjtoP.mjs";
+//#region src/types.d.ts
+/** RFC 8628 §3.2 — device authorization response. */
+interface DeviceAuthorizationResponse {
+  /** High-entropy secret the device polls with. Never shown to the user. */
+  device_code: string;
+  /** Short code the user reads off the screen and types (or verifies). */
+  user_code: string;
+  /** Where the user goes to authorize. */
+  verification_uri: string;
+  /**
+   * `verification_uri` with the `user_code` embedded, for QR/NFC.
+   * OPTIONAL in the spec; we always emit it because the QR path is the point.
+   */
+  verification_uri_complete?: string;
+  /** Lifetime in seconds of BOTH codes. */
+  expires_in: number;
+  /** Minimum seconds between polls. Spec default is 5. */
+  interval: number;
+}
+/** RFC 8628 §3.5 — token endpoint error codes for this grant. */
+type DeviceAuthorizationError =
+/** Keep polling; the user has not finished yet. */
+`authorization_pending` |
+/** Keep polling, but permanently add 5s to the interval. */
+`slow_down` |
+/** Stop. The user said no. */
+`access_denied` |
+/** Stop. The codes aged out. */
+`expired_token`;
+/** The grant type URN. Sent verbatim as `grant_type`. */
+declare const DEVICE_CODE_GRANT_TYPE: "urn:ietf:params:oauth:grant-type:device_code";
+/**
+ * Lifecycle of one authorization attempt.
+ *
+ * Aliased from `machine.ts`, which owns the states and the legal transitions
+ * between them. Kept under its record-field name so a store adapter can type
+ * its status column without importing the machine.
+ */
+type GrantStatus = GrantState;
+/**
+ * A stored authorization attempt.
+ *
+ * `subject` is whatever the host app uses to identify the approving user (a
+ * DID, a user id, a session id). hanko never interprets it — it only carries it
+ * from the approving device back to the polling device.
+ */
+interface DeviceGrant {
+  device_code: string;
+  user_code: string;
+  status: GrantStatus;
+  /** Epoch ms. Compared against an injected clock, never `Date.now()` directly. */
+  expiresAt: number;
+  /** Seconds. Mutable: `slow_down` raises it. */
+  interval: number;
+  /** OAuth client that started the flow, if the host app tracks clients. */
+  clientId?: string;
+  /** Requested scopes, uninterpreted. */
+  scope?: string;
+  /** Set when status becomes `approved`. */
+  subject?: string;
+  /** Epoch ms of the last poll, for `slow_down` enforcement. */
+  lastPolledAt?: number;
+}
+/**
+ * Persistence boundary.
+ *
+ * Deliberately tiny so adapters (Redis, Supabase, Better-Auth, Durable Objects)
+ * are trivial. All methods may be async. Lookup by BOTH codes is required: the
+ * device polls by `device_code`, the user approves by `user_code`.
+ */
+interface DeviceGrantStore {
+  create(grant: DeviceGrant): Promise<void> | void;
+  findByDeviceCode(deviceCode: string): Promise<DeviceGrant | null> | DeviceGrant | null;
+  findByUserCode(userCode: string): Promise<DeviceGrant | null> | DeviceGrant | null;
+  update(grant: DeviceGrant): Promise<void> | void;
+  /** Drop expired grants. Called opportunistically; may be a no-op with TTL stores. */
+  prune?(now: number): Promise<void> | void;
+}
+//#endregion
+export { DeviceGrantStore as a, DeviceGrant as i, DeviceAuthorizationError as n, DeviceAuthorizationResponse as r, DEVICE_CODE_GRANT_TYPE as t };
+//# sourceMappingURL=types-C82lb-zX.d.mts.map

package/dist/types-C82lb-zX.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-C82lb-zX.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;UAaiB;;EAEf;;EAEA;;EAEA;;;;;EAKA;;EAEA;;EAEA;;;KAIU;;;;;;;;;;cAWC;;;;;;;;KAUD,cAAc;;;;;;;;UAST;EACf;EACA;EACA,QAAQ;;EAER;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;UAUe;EACf,OAAO,OAAO,cAAc;EAC5B,iBACE,qBACC,QAAQ,sBAAsB;EACjC,eACE,mBACC,QAAQ,sBAAsB;EACjC,OAAO,OAAO,cAAc;;EAE5B,OAAO,cAAc"}