@mymehq/sdk 4.0.0 → 4.1.1

package/dist/auth/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Token storage interface and default implementations.
+ *
+ * Browser default: localStorage keyed by `(origin, client_id)`.
+ * Node default: in-memory; Node consumers can pass a file-backed
+ * implementation if they need cross-process persistence.
+ */
+interface TokenStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare class InMemoryTokenStorage implements TokenStorage {
+    private map;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare class LocalStorageTokenStorage implements TokenStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** Pick the most appropriate default storage for the current runtime. */
+declare function defaultTokenStorage(): TokenStorage;
+
+/** TokenProvider gives MymeClient an access token for every request. */
+interface TokenProvider {
+    /** Returns a non-expired access token. Refreshes proactively if < 60s
+     *  remain on the current one. Single-flight: concurrent callers await
+     *  the same in-flight refresh promise. */
+    getAccessToken(): Promise<string>;
+    /** Subscribe to sign-out events (fired on invalid_grant /
+     *  token_reuse_detected). Returns an unsubscribe fn. */
+    onSignOut(handler: () => void): () => void;
+    /** Force a sign-out — clears local storage, fires onSignOut handlers. */
+    signOut(): Promise<void>;
+}
+
+/**
+ * MymeAuth — owns the OAuth dance for browser apps signing into Myme.
+ *
+ * Flow:
+ *   const auth = new MymeAuth({ issuer, clientId, redirectUri, scopes });
+ *   // On a "Sign in" click:
+ *   window.location.href = await auth.buildAuthorizeUrl();
+ *   // On the callback page:
+ *   const provider = await auth.handleCallback(window.location.href);
+ *   const client = new MymeClient({ url: issuer, tokenProvider: provider });
+ *
+ * Restoration on page load: `await auth.restore()` returns a TokenProvider
+ * if a session is in storage, null otherwise.
+ *
+ * Sign-out: `await auth.signOut(provider)` revokes locally and clears
+ * persisted tokens; visible "session expired" UX is the caller's
+ * responsibility (subscribe via provider.onSignOut).
+ */
+interface MymeAuthConfig {
+    /** Myme server URL — protocol + host (and port). */
+    issuer: string;
+    /** OAuth client id, registered via POST /auth/clients. */
+    clientId: string;
+    /** Exact-match redirect URI. Must be registered for this client. */
+    redirectUri: string;
+    /** Scopes to request (e.g. ["core.note:read", "core.note:write"]). */
+    scopes: string[];
+    /** Token storage. Defaults to localStorage in browser, in-memory in Node. */
+    storage?: TokenStorage;
+    /** Override for the global fetch (testing). */
+    fetch?: typeof globalThis.fetch;
+}
+declare class MymeAuth {
+    private readonly issuer;
+    private readonly clientId;
+    private readonly redirectUri;
+    private readonly scopes;
+    private readonly storage;
+    private readonly fetch;
+    private readonly pendingKey;
+    private readonly tokensKey;
+    constructor(config: MymeAuthConfig);
+    /** Build the authorize URL and persist the PKCE verifier + state. */
+    buildAuthorizeUrl(opts?: {
+        state?: string;
+    }): Promise<string>;
+    /**
+     * Exchange the authorization code for tokens. Call from your `/callback`
+     * route handler with `window.location.href` (or the equivalent server-
+     * side request URL). Throws OAuthError on failure.
+     */
+    handleCallback(callbackUrl: string): Promise<TokenProvider>;
+    /** Restore a TokenProvider from persisted storage; null if no session. */
+    restore(): Promise<TokenProvider | null>;
+    /** Sign out — clears persisted tokens. */
+    signOut(provider: TokenProvider): Promise<void>;
+}
+
+/**
+ * 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";
+declare class OAuthError extends Error {
+    readonly code: OAuthErrorCode;
+    readonly status: number;
+    constructor(code: OAuthErrorCode, message: string, status?: number);
+}
+
+/**
+ * PKCE primitives — RFC 7636. Verifier is 43–128 chars of base64url
+ * generated from random bytes; challenge is BASE64URL(SHA-256(verifier)).
+ *
+ * Uses Web Crypto so the auth subpath is universal (browser + Node 15+
+ * + Cloudflare Workers + Deno). The SDK's data-plane root path keeps
+ * its node:crypto dependency for HMAC webhook verification; nothing
+ * Node-only leaks into ./auth.
+ */
+/**
+ * Generate a fresh PKCE code verifier. Default length 64 — within RFC's
+ * 43–128 range; longer is harder to brute force, shorter speeds up dev
+ * tooling. 64 is a balanced default.
+ */
+declare function generateCodeVerifier(length?: number): string;
+/** Compute the S256 challenge: BASE64URL(SHA-256(verifier)). */
+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 };

package/dist/auth/index.js

@@ -0,0 +1,331 @@
+// src/auth/storage.ts
+var InMemoryTokenStorage = class {
+  map = /* @__PURE__ */ new Map();
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async get(key) {
+    return this.map.get(key) ?? null;
+  }
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async set(key, value) {
+    this.map.set(key, value);
+  }
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async delete(key) {
+    this.map.delete(key);
+  }
+};
+var LocalStorageTokenStorage = class {
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async get(key) {
+    return globalThis.localStorage.getItem(key);
+  }
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async set(key, value) {
+    globalThis.localStorage.setItem(key, value);
+  }
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async delete(key) {
+    globalThis.localStorage.removeItem(key);
+  }
+};
+function defaultTokenStorage() {
+  if (typeof globalThis.localStorage !== "undefined") {
+    return new LocalStorageTokenStorage();
+  }
+  return new InMemoryTokenStorage();
+}
+
+// src/auth/pkce.ts
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+function base64url(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateCodeVerifier(length = 64) {
+  if (length < 43 || length > 128) {
+    throw new Error(
+      `PKCE verifier length must be 43-128, got ${String(length)}`
+    );
+  }
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  let out = "";
+  for (const byte of bytes) {
+    out += ALPHABET.charAt(byte % ALPHABET.length);
+  }
+  return out;
+}
+async function computeCodeChallenge(verifier) {
+  const data = new TextEncoder().encode(verifier);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return base64url(new Uint8Array(hash));
+}
+function generateState(byteLength = 16) {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+// src/auth/errors.ts
+var OAuthError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status = 400) {
+    super(message);
+    this.name = "OAuthError";
+    this.code = code;
+    this.status = status;
+  }
+};
+
+// src/auth/token-provider.ts
+var PROACTIVE_WINDOW_MS = 6e4;
+var StoredTokenProvider = class {
+  issuer;
+  clientId;
+  storage;
+  storageKey;
+  fetch;
+  cache = null;
+  inflightRefresh = null;
+  signOutHandlers = /* @__PURE__ */ new Set();
+  constructor(config) {
+    this.issuer = config.issuer.replace(/\/+$/, "");
+    this.clientId = config.clientId;
+    this.storage = config.storage;
+    this.storageKey = config.storageKey;
+    this.fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  async hydrateFromStorage() {
+    const raw = await this.storage.get(this.storageKey);
+    if (!raw) return false;
+    try {
+      this.cache = JSON.parse(raw);
+      return true;
+    } catch {
+      await this.storage.delete(this.storageKey);
+      return false;
+    }
+  }
+  async persist(tokens) {
+    this.cache = tokens;
+    await this.storage.set(this.storageKey, JSON.stringify(tokens));
+  }
+  async getAccessToken() {
+    if (!this.cache) {
+      const ok = await this.hydrateFromStorage();
+      if (!ok) {
+        throw new OAuthError("invalid_grant", "No active session", 401);
+      }
+    }
+    if (!this.cache) {
+      throw new OAuthError("invalid_grant", "No active session", 401);
+    }
+    const remaining = this.cache.access_expires_at - Date.now();
+    if (remaining > PROACTIVE_WINDOW_MS) {
+      return this.cache.access_token;
+    }
+    return this.refresh();
+  }
+  /** Single-flight refresh — concurrent callers await the same promise. */
+  async refresh() {
+    if (this.inflightRefresh) return this.inflightRefresh;
+    if (!this.cache) {
+      throw new OAuthError("invalid_grant", "No refresh token available", 401);
+    }
+    const refreshToken = this.cache.refresh_token;
+    const previousScope = this.cache.scope;
+    this.inflightRefresh = (async () => {
+      try {
+        const res = await this.fetch(`${this.issuer}/auth/token`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: this.clientId
+          })
+        });
+        const body = await res.json();
+        if (!res.ok || !body.access_token) {
+          await this.signOut();
+          throw new OAuthError(
+            body.error ?? "invalid_grant",
+            body.error ?? "Refresh failed",
+            res.status
+          );
+        }
+        const expiresInMs = (body.expires_in ?? 3600) * 1e3;
+        const updated = {
+          access_token: body.access_token,
+          refresh_token: body.refresh_token ?? refreshToken,
+          access_expires_at: Date.now() + expiresInMs,
+          scope: body.scope ?? previousScope
+        };
+        await this.persist(updated);
+        return updated.access_token;
+      } finally {
+        this.inflightRefresh = null;
+      }
+    })();
+    return this.inflightRefresh;
+  }
+  onSignOut(handler) {
+    this.signOutHandlers.add(handler);
+    return () => this.signOutHandlers.delete(handler);
+  }
+  async signOut() {
+    this.cache = null;
+    await this.storage.delete(this.storageKey);
+    for (const h of this.signOutHandlers) {
+      try {
+        h();
+      } catch {
+      }
+    }
+  }
+};
+
+// src/auth/auth.ts
+var MymeAuth = class {
+  issuer;
+  clientId;
+  redirectUri;
+  scopes;
+  storage;
+  fetch;
+  pendingKey;
+  tokensKey;
+  constructor(config) {
+    this.issuer = config.issuer.replace(/\/+$/, "");
+    this.clientId = config.clientId;
+    this.redirectUri = config.redirectUri;
+    this.scopes = config.scopes;
+    this.storage = config.storage ?? defaultTokenStorage();
+    this.fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+    const origin = (() => {
+      try {
+        return new URL(this.issuer).origin;
+      } catch {
+        return this.issuer;
+      }
+    })();
+    this.pendingKey = `myme.auth.pending:${origin}:${config.clientId}`;
+    this.tokensKey = `myme.auth.tokens:${origin}:${config.clientId}`;
+  }
+  /** Build the authorize URL and persist the PKCE verifier + state. */
+  async buildAuthorizeUrl(opts) {
+    const verifier = generateCodeVerifier();
+    const challenge = await computeCodeChallenge(verifier);
+    const state = opts?.state ?? generateState();
+    const pending = {
+      verifier,
+      state,
+      redirectUri: this.redirectUri
+    };
+    await this.storage.set(this.pendingKey, JSON.stringify(pending));
+    const url = new URL(`${this.issuer}/auth/authorize`);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", this.clientId);
+    url.searchParams.set("redirect_uri", this.redirectUri);
+    url.searchParams.set("scope", this.scopes.join(" "));
+    url.searchParams.set("code_challenge", challenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("state", state);
+    return url.toString();
+  }
+  /**
+   * Exchange the authorization code for tokens. Call from your `/callback`
+   * route handler with `window.location.href` (or the equivalent server-
+   * side request URL). Throws OAuthError on failure.
+   */
+  async handleCallback(callbackUrl) {
+    const url = new URL(callbackUrl);
+    const error = url.searchParams.get("error");
+    if (error) {
+      throw new OAuthError(
+        error === "access_denied" ? "access_denied" : "invalid_request",
+        url.searchParams.get("error_description") ?? error
+      );
+    }
+    const code = url.searchParams.get("code");
+    const incomingState = url.searchParams.get("state");
+    if (!code) {
+      throw new OAuthError("invalid_request", "Missing authorization code");
+    }
+    const pendingRaw = await this.storage.get(this.pendingKey);
+    if (!pendingRaw) {
+      throw new OAuthError(
+        "invalid_request",
+        "No pending PKCE verifier \u2014 did you call buildAuthorizeUrl in a different browser context?"
+      );
+    }
+    const pending = JSON.parse(pendingRaw);
+    if (pending.state !== incomingState) {
+      throw new OAuthError("invalid_request", "State mismatch on callback");
+    }
+    const res = await this.fetch(`${this.issuer}/auth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "authorization_code",
+        code,
+        code_verifier: pending.verifier,
+        redirect_uri: pending.redirectUri,
+        client_id: this.clientId
+      })
+    });
+    const body = await res.json();
+    if (!res.ok || !body.access_token || !body.refresh_token) {
+      const errCode = body.error ? body.error : "invalid_grant";
+      throw new OAuthError(
+        errCode,
+        body.error_description ?? body.error ?? "Token exchange failed",
+        res.status
+      );
+    }
+    await this.storage.delete(this.pendingKey);
+    const provider = new StoredTokenProvider({
+      issuer: this.issuer,
+      clientId: this.clientId,
+      storage: this.storage,
+      storageKey: this.tokensKey,
+      fetch: this.fetch
+    });
+    await provider.persist({
+      access_token: body.access_token,
+      refresh_token: body.refresh_token,
+      access_expires_at: Date.now() + (body.expires_in ?? 3600) * 1e3,
+      scope: body.scope ?? this.scopes.join(" ")
+    });
+    return provider;
+  }
+  /** Restore a TokenProvider from persisted storage; null if no session. */
+  async restore() {
+    const provider = new StoredTokenProvider({
+      issuer: this.issuer,
+      clientId: this.clientId,
+      storage: this.storage,
+      storageKey: this.tokensKey,
+      fetch: this.fetch
+    });
+    const ok = await provider.hydrateFromStorage();
+    return ok ? provider : null;
+  }
+  /** Sign out — clears persisted tokens. */
+  async signOut(provider) {
+    await provider.signOut();
+    await this.storage.delete(this.pendingKey);
+  }
+};
+export {
+  InMemoryTokenStorage,
+  LocalStorageTokenStorage,
+  MymeAuth,
+  OAuthError,
+  computeCodeChallenge,
+  defaultTokenStorage,
+  generateCodeVerifier,
+  generateState
+};

package/dist/index.d.ts

@@ -47,9 +47,25 @@ interface ConflictAutoMergedEvent {
 /** Optional callback fired when the auto-merge path completes successfully. */
 type ConflictAutoMergeListener = (event: ConflictAutoMergedEvent) => void | Promise<void>;
 
-interface ClientConfig {
-    url: string;
+/** Minimal token provider shape — full interface lives in
+ *  @mymehq/sdk/auth. Kept loose here so the data root doesn't depend
+ *  on the auth subpath. */
+interface TokenProviderLike {
+    getAccessToken(): Promise<string>;
+}
+/**
+ * Credentials are mutually exclusive at the type level: pass either a
+ * static API key (myme_k1_*) or an OAuth token provider (myme_at_*).
+ */
+type ClientCredential = {
     apiKey: string;
+    tokenProvider?: never;
+} | {
+    tokenProvider: TokenProviderLike;
+    apiKey?: never;
+};
+type ClientConfig = ClientCredential & {
+    url: string;
     fetch?: typeof globalThis.fetch;
     /**
      * Default conflict resolution strategy for all updates.
@@ -67,7 +83,7 @@ interface ClientConfig {
     onConflictAutoMerge?: ConflictAutoMergeListener;
     timeoutMs?: number;
     cdnBaseUrl?: string;
-}
+};
 interface UpdateOptions {
     /**
      * Version the caller expects the item to currently be at. When provided,
@@ -510,9 +526,9 @@ declare class MymeClient {
             limit?: number;
         }) => Promise<WebhookDelivery[]>;
     };
-    /** Tenant-scoped configuration (per-type ambient retention overrides
-     * today; future tenant-level settings will live here). All endpoints
-     * are admin-only. */
+    /** Tenant-scoped configuration. Controls feed-tier retention per type
+     * and the three optional schema-enforcement levers (TSC42 §5). All
+     * endpoints are admin-only. */
     readonly tenants: {
         /** Returns the current tenant's config. Empty object when nothing
          * is configured. */

package/dist/index.js

@@ -55,14 +55,35 @@ var DEFAULT_TIMEOUT_MS = 3e4;
 var HttpTransport = class {
   baseUrl;
   apiKey;
+  tokenProvider;
   fetch;
   timeoutMs;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/+$/, "");
     this.apiKey = config.apiKey;
+    this.tokenProvider = config.tokenProvider;
+    if (!this.apiKey && !this.tokenProvider) {
+      throw new Error(
+        "MymeClient requires either { apiKey } or { tokenProvider }"
+      );
+    }
     this.fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   }
+  /** Resolves the current Authorization header value. For tokenProvider
+   *  callers this may trigger a proactive refresh under the hood. */
+  async getAuthHeader() {
+    if (this.apiKey) return `Bearer ${this.apiKey}`;
+    if (!this.tokenProvider) {
+      throw new MymeError(
+        "configuration_error",
+        "MymeClient has no apiKey or tokenProvider \u2014 this should be unreachable",
+        0
+      );
+    }
+    const token = await this.tokenProvider.getAccessToken();
+    return `Bearer ${token}`;
+  }
   async request(method, path, options) {
     const response = await this.rawRequest(method, path, options);
     if (response.status === 204) {
@@ -93,7 +114,7 @@ var HttpTransport = class {
   async rawRequest(method, path, options) {
     const url = this.buildUrl(path, options?.query);
     const headers = {
-      Authorization: `Bearer ${this.apiKey}`,
+      Authorization: await this.getAuthHeader(),
       ...options?.headers
     };
     const controller = new AbortController();
@@ -320,6 +341,7 @@ var MymeClient = class {
     this.transport = new HttpTransport({
       baseUrl: config.url,
       apiKey: config.apiKey,
+      tokenProvider: config.tokenProvider,
       fetch: config.fetch,
       timeoutMs: config.timeoutMs
     });
@@ -814,9 +836,9 @@ var MymeClient = class {
     }
   };
   // ---- Tenants (admin) ----
-  /** Tenant-scoped configuration (per-type ambient retention overrides
-   * today; future tenant-level settings will live here). All endpoints
-   * are admin-only. */
+  /** Tenant-scoped configuration. Controls feed-tier retention per type
+   * and the three optional schema-enforcement levers (TSC42 §5). All
+   * endpoints are admin-only. */
   tenants = {
     /** Returns the current tenant's config. Empty object when nothing
      * is configured. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mymehq/sdk",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -10,13 +10,17 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@mymehq/shared": "4.0.0"
+    "@mymehq/shared": "4.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",