@mymehq/sdk 4.1.1 → 4.3.0

package/dist/auth/index.d.ts

@@ -35,6 +35,11 @@ interface TokenProvider {
     onSignOut(handler: () => void): () => void;
     /** Force a sign-out — clears local storage, fires onSignOut handlers. */
     signOut(): Promise<void>;
+    /** Force a token refresh and return the new access token. Same single-flight
+     *  semantics as `getAccessToken()`. Consumers calling on a 401 response
+     *  should use this rather than waiting for the next `getAccessToken()` to
+     *  hit the proactive window. */
+    refresh(): Promise<string>;
 }
 
 /**
@@ -99,7 +104,7 @@ declare class MymeAuth {
  * Typed OAuth error surface. Mirrors the wire `error` codes from
  * RFC 6749 §5.2 and the rotation-replay extension.
  */
-type OAuthErrorCode = "invalid_request" | "invalid_client" | "invalid_grant" | "invalid_scope" | "invalid_token" | "unauthorized_client" | "unsupported_grant_type" | "unsupported_response_type" | "access_denied" | "insufficient_scope" | "token_reuse_detected" | "server_error" | "temporarily_unavailable";
+type OAuthErrorCode = "invalid_request" | "invalid_client" | "invalid_grant" | "invalid_scope" | "invalid_token" | "unauthorized_client" | "unsupported_grant_type" | "unsupported_response_type" | "access_denied" | "insufficient_scope" | "token_reuse_detected" | "server_error" | "temporarily_unavailable" | "authorization_pending" | "slow_down" | "expired_token";
 declare class OAuthError extends Error {
     readonly code: OAuthErrorCode;
     readonly status: number;
@@ -126,4 +131,57 @@ declare function computeCodeChallenge(verifier: string): Promise<string>;
 /** Generate a random opaque state value for CSRF protection on the redirect. */
 declare function generateState(byteLength?: number): string;
 
-export { InMemoryTokenStorage, LocalStorageTokenStorage, MymeAuth, type MymeAuthConfig, OAuthError, type OAuthErrorCode, type TokenProvider, type TokenStorage, computeCodeChallenge, defaultTokenStorage, generateCodeVerifier, generateState };
+/**
+ * Device Authorization Grant flow (RFC 8628) — for headless / CLI / native
+ * apps that can't host a browser callback.
+ *
+ *   const handle = await startDeviceFlow({ issuer, clientId, scopes });
+ *   console.log(`Visit ${handle.verification_uri} and enter ${handle.user_code}`);
+ *   const provider = await handle.pollForToken();
+ *
+ * `pollForToken()` blocks until the user approves on the server (returning
+ * a `TokenProvider`), the user denies (throws OAuthError "access_denied"),
+ * or the device_code expires (throws OAuthError "expired_token"). Adheres
+ * to RFC 8628 polling rules: respects `interval`, doubles on `slow_down`.
+ */
+
+interface StartDeviceFlowConfig {
+    /** Myme server URL — protocol + host (and port). */
+    issuer: string;
+    /** OAuth client id, registered via POST /auth/clients. */
+    clientId: string;
+    /** Scopes to request (e.g. ["core.note:read"]). */
+    scopes: string[];
+    /** Token storage for persisting the resulting access/refresh tokens.
+     *  Defaults to localStorage in browser, in-memory in Node. CLI consumers
+     *  typically pass a filesystem-backed implementation. */
+    storage?: TokenStorage;
+    /** Override for the global fetch (testing). */
+    fetch?: typeof globalThis.fetch;
+}
+interface DeviceFlowHandle {
+    /** Short, human-readable code the user types on the verification page
+     *  (XXXX-XXXX shape). */
+    user_code: string;
+    /** URL the user should visit. */
+    verification_uri: string;
+    /** Same URL with `?user_code=…` appended; some clients can render this
+     *  as a deep link / QR code so the user doesn't have to type. */
+    verification_uri_complete: string;
+    /** Seconds the device_code remains valid. */
+    expires_in: number;
+    /** Minimum seconds between polls. */
+    interval: number;
+    /** Block until the user approves on the server. Resolves with a
+     *  TokenProvider that can be passed straight into `MymeClient`.
+     *  Rejects with OAuthError on denial / expiry / fatal error. */
+    pollForToken(options?: {
+        signal?: AbortSignal;
+    }): Promise<TokenProvider>;
+}
+/** Initiate a Device Authorization Grant flow. The returned handle
+ *  carries the user-facing code + URL plus a `pollForToken()` that
+ *  blocks until approval. */
+declare function startDeviceFlow(config: StartDeviceFlowConfig): Promise<DeviceFlowHandle>;
+
+export { type DeviceFlowHandle, InMemoryTokenStorage, LocalStorageTokenStorage, MymeAuth, type MymeAuthConfig, OAuthError, type OAuthErrorCode, type StartDeviceFlowConfig, type TokenProvider, type TokenStorage, computeCodeChallenge, defaultTokenStorage, generateCodeVerifier, generateState, startDeviceFlow };

package/dist/auth/index.js

@@ -128,7 +128,9 @@ var StoredTokenProvider = class {
     }
     return this.refresh();
   }
-  /** Single-flight refresh — concurrent callers await the same promise. */
+  /** Single-flight refresh — concurrent callers await the same promise.
+   *  Public so consumers can force a refresh on 401 responses (RFC 6750
+   *  invalid_token) without waiting for the proactive-refresh window. */
   async refresh() {
     if (this.inflightRefresh) return this.inflightRefresh;
     if (!this.cache) {
@@ -319,6 +321,127 @@ var MymeAuth = class {
     await this.storage.delete(this.pendingKey);
   }
 };
+
+// src/auth/device-flow.ts
+var DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+var DEFAULT_POLL_INTERVAL_MS = 5e3;
+var SLOW_DOWN_BUMP_MS = 5e3;
+async function startDeviceFlow(config) {
+  const issuer = config.issuer.replace(/\/+$/, "");
+  const fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+  const storage = config.storage ?? defaultTokenStorage();
+  const initiateRes = await fetchImpl(`${issuer}/auth/device`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      client_id: config.clientId,
+      scope: config.scopes.join(" ")
+    })
+  });
+  if (!initiateRes.ok) {
+    const body = await safeJson(initiateRes);
+    const errCode = extractErrorCode(body);
+    throw new OAuthError(
+      errCode,
+      `device_authorization initiate failed: ${String(initiateRes.status)}`
+    );
+  }
+  const initiated = await initiateRes.json();
+  let pollIntervalMs = typeof initiated.interval === "number" ? initiated.interval * 1e3 : DEFAULT_POLL_INTERVAL_MS;
+  const handle = {
+    user_code: initiated.user_code,
+    verification_uri: initiated.verification_uri,
+    verification_uri_complete: initiated.verification_uri_complete,
+    expires_in: initiated.expires_in,
+    interval: initiated.interval,
+    async pollForToken(options) {
+      const deadline = Date.now() + initiated.expires_in * 1e3;
+      while (Date.now() < deadline) {
+        if (options?.signal?.aborted) {
+          throw new OAuthError(
+            "invalid_request",
+            "Device flow aborted by caller"
+          );
+        }
+        await sleep(pollIntervalMs, options?.signal);
+        const res = await fetchImpl(`${issuer}/auth/device/token`, {
+          method: "POST",
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+          body: new URLSearchParams({
+            grant_type: DEVICE_GRANT_TYPE,
+            device_code: initiated.device_code,
+            client_id: config.clientId
+          }).toString()
+        });
+        if (res.ok) {
+          const tokens = await res.json();
+          const storageKey = `myme.auth.tokens:${new URL(issuer).origin}:${config.clientId}`;
+          const provider = new StoredTokenProvider({
+            issuer,
+            clientId: config.clientId,
+            storage,
+            storageKey,
+            fetch: fetchImpl
+          });
+          await provider.persist({
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token,
+            access_expires_at: Date.now() + tokens.expires_in * 1e3,
+            scope: tokens.scope
+          });
+          return provider;
+        }
+        const body = await safeJson(res);
+        const code = body.error ?? "invalid_grant";
+        if (code === "authorization_pending") continue;
+        if (code === "slow_down") {
+          pollIntervalMs += SLOW_DOWN_BUMP_MS;
+          continue;
+        }
+        throw new OAuthError(
+          code,
+          body.error_description ?? "Device flow failed"
+        );
+      }
+      throw new OAuthError("expired_token", "Device flow expired");
+    }
+  };
+  return handle;
+}
+async function safeJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+function extractErrorCode(body) {
+  const err = body.error;
+  if (typeof err === "string") return err;
+  if (typeof err === "object" && err !== null) {
+    const code = err.code;
+    if (typeof code === "string") return code;
+  }
+  return "invalid_request";
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      signal?.removeEventListener("abort", onAbort);
+      reject(new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort);
+  });
+}
 export {
   InMemoryTokenStorage,
   LocalStorageTokenStorage,
@@ -327,5 +450,6 @@ export {
   computeCodeChallenge,
   defaultTokenStorage,
   generateCodeVerifier,
-  generateState
+  generateState,
+  startDeviceFlow
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mymehq/sdk",
-  "version": "4.1.1",
+  "version": "4.3.0",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -20,7 +20,7 @@
     "dist"
   ],
   "dependencies": {
-    "@mymehq/shared": "4.1.1"
+    "@mymehq/shared": "4.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",