@basictech/react 0.7.0 → 0.8.0-beta.1

package/src/core/db/RemoteCollection.ts

@@ -59,23 +59,26 @@ export class RemoteCollection<T extends { id: string } = Record<string, any> & {
 
     this.log(`${method} ${url}`, body ? JSON.stringify(body) : '')
 
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${token}`
+    }
+    if (body) {
+      headers['Content-Type'] = 'application/json'
+    }
+
     const response = await fetch(url, {
       method,
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${token}`
-      },
+      headers,
       ...(body ? { body: JSON.stringify(body) } : {})
     })
 
     const responseData = await response.json().catch(() => ({}))
 
     if (!response.ok) {
-      // Handle 401 Unauthorized - token may have expired
+      // Handle 401 Unauthorized - force refresh then retry once
       if (response.status === 401 && !isRetry) {
-        this.log('Got 401, retrying with fresh token...')
-        // getToken() should refresh the token if expired
-        // Retry the request once
+        this.log('Got 401, forcing token refresh and retrying...')
+        await this.config.getToken({ forceRefresh: true })
         return this.request<R>(method, path, body, true)
       }
 
@@ -83,16 +86,27 @@ export class RemoteCollection<T extends { id: string } = Record<string, any> & {
         console.error(`[RemoteDB] Error ${response.status}:`, responseData)
       }
       
-      // Call onAuthError callback if provided and this is an auth error
-      if (response.status === 401 && this.config.onAuthError) {
-        this.config.onAuthError({
-          status: response.status,
-          message: 'Authentication failed',
-          response: responseData
-        })
+      // Call onAuthError callback for auth/authz errors
+      if (this.config.onAuthError) {
+        if (response.status === 401) {
+          this.config.onAuthError({
+            status: response.status,
+            message: 'Authentication failed',
+            response: responseData,
+            errorType: 'expired',
+            afterRetry: isRetry,
+          })
+        } else if (response.status === 403) {
+          this.config.onAuthError({
+            status: response.status,
+            message: responseData.message || 'Forbidden - insufficient permissions or missing scope',
+            response: responseData,
+            errorType: 'forbidden',
+            afterRetry: isRetry,
+          })
+        }
       }
 
-      // Try different error message fields that APIs commonly use
       const errorMessage = responseData.message || responseData.error || responseData.detail || 
         (typeof responseData === 'string' ? responseData : `API request failed: ${response.status}`)
       throw new RemoteDBError(errorMessage, response.status, responseData)

package/src/core/db/index.ts

@@ -1,5 +1,5 @@
 // Core DB exports
-export type { Collection, BasicDB, DBMode, RemoteDBConfig } from './types'
+export type { Collection, BasicDB, DBMode, RemoteDBConfig, GetTokenOptions } from './types'
 export type { AuthError } from './types'
 export { RemoteDBError } from './types'
 export { RemoteDB } from './RemoteDB'

package/src/core/db/types.ts

@@ -91,6 +91,10 @@ export interface AuthError {
   status: number
   message: string
   response?: any
+  /** Classifies the error for UI display (e.g. "session expired" vs "forbidden") */
+  errorType: 'expired' | 'forbidden' | 'revoked' | 'network' | 'unknown'
+  /** True if this error occurred after a retry with a refreshed token */
+  afterRetry: boolean
 }
 
 /**
@@ -109,13 +113,21 @@ export class RemoteDBError extends Error {
   }
 }
 
+/**
+ * Options for getToken (e.g. force refresh after 401)
+ */
+export interface GetTokenOptions {
+  /** When true, refresh the access token before returning (e.g. after server returned 401) */
+  forceRefresh?: boolean
+}
+
 /**
  * Configuration for RemoteDB
  */
 export interface RemoteDBConfig {
   serverUrl: string
   projectId: string
-  getToken: () => Promise<string>
+  getToken: (options?: GetTokenOptions) => Promise<string>
   schema?: any
   /** Enable debug logging (default: false) */
   debug?: boolean

package/src/index.ts

@@ -13,6 +13,7 @@ export type {
     BasicContextType,
     AuthResult
 } from "./AuthContext"
+export { DBStatus } from "./AuthContext"
 
 // Core DB exports
 export type { 
@@ -20,10 +21,15 @@ export type {
     BasicDB, 
     Collection, 
     RemoteDBConfig,
+    GetTokenOptions,
     AuthError
 } from "./core/db"
 
 export { RemoteDB, RemoteCollection, RemoteDBError, NotAuthenticatedError } from "./core/db"
 
 // Storage utilities
-export { STORAGE_KEYS } from "./utils/storage"
+export { STORAGE_KEYS } from "./utils/storage"
+
+// DID resolution
+export { resolveDid, resolveHandle, resolveDidWebUrl } from "./utils/resolveDid"
+export type { ResolvedDid } from "./utils/resolveDid"

package/src/sync/index.ts

@@ -4,7 +4,8 @@ import { v7 as uuidv7 } from 'uuid';
 import { Dexie } from 'dexie';
 
 import { log } from '../config'
-import { validateSchema, validateData } from '@basictech/schema'
+import { validateData } from '@basictech/schema'
+import { setTokenGetter } from './tokenRegistry'
 
 // Track initialization state
 let dexieExtensionsLoaded = false;
@@ -58,40 +59,29 @@ export class BasicSync extends Dexie {
   constructor(name: string, options: any) {
     super(name, options);
 
-    // --- INIT SCHEMA --- // 
-
-    //todo: handle versions?
-
-    // TODO: validate schema
+    // --- INIT SCHEMA --- //
     this.basic_schema = options.schema
     this.version(1).stores(this._convertSchemaToDxSchema(this.basic_schema))
-
     this.version(2).stores({})
-    // this.verssion
 
-
-    // create an alias for toArray
-    // @ts-ignore
+    // @ts-ignore - alias for toArray
     this.Collection.prototype.get = this.Collection.prototype.toArray
-
-
-    // --- SYNC --- // 
-
-    // this.syncable.on("statusChanged", (status, url) => { 
-    //   console.log("statusChanged", status, url)
-    // })
-
   }
 
-  async connect({ access_token, ws_url }: { access_token: string, ws_url?: string }) {
+  async connect({ getToken, ws_url }: { getToken: (opts?: { forceRefresh?: boolean }) => Promise<string>, ws_url?: string }) {
     const WS_URL = ws_url || 'wss://pds.basic.id/ws'
 
     log('Connecting to', WS_URL)
 
+    // Store getToken in module-level registry (not in options) because
+    // dexie-syncable serializes options into IndexedDB via structured clone,
+    // which cannot handle functions.
+    setTokenGetter(WS_URL, getToken)
+
     await this.updateSyncNodes();
     
     log('Starting connection...')
-    return this.syncable.connect("websocket", WS_URL, { authToken: access_token, schema: this.basic_schema });
+    return this.syncable.connect("websocket", WS_URL, { schema: this.basic_schema });
   }
 
   async disconnect({ ws_url }: { ws_url?: string } = {}) {
@@ -128,7 +118,6 @@ export class BasicSync extends Dexie {
           log(`HEISENBUG: Setting ${node.id} to ${node.id === largestNodeId ? 'master' : '0'}`);
         }
 
-        // add delay to ensure sync nodes are updated // i dont think this helps?
         await new Promise(resolve => setTimeout(resolve, 1000));
 
         if (typeof window !== 'undefined') {
@@ -149,8 +138,10 @@ export class BasicSync extends Dexie {
 
   _convertSchemaToDxSchema(schema: any) {
     const stores = Object.entries(schema.tables).map(([key, table]: any) => {
-
-      const indexedFields = Object.entries(table.fields).filter(([key, field]: any) => field.indexed).map(([key, field]: any) => `,${key}`).join('')
+      const indexedFields = Object.entries(table.fields)
+        .filter(([, field]: any) => field.indexed)
+        .map(([fieldKey]: any) => `,${fieldKey}`)
+        .join('')
       return {
         [key]: 'id' + indexedFields
       }
@@ -160,11 +151,6 @@ export class BasicSync extends Dexie {
   }
 
   debugeroo() {
-    // console.log("debugeroo", this.syncable)
-
-    // this.syncable.list().then(x => console.log(x))
-
-    // this.syncable
     return this.syncable
   }
 

package/src/sync/syncProtocol.js

@@ -1,11 +1,24 @@
 "use client"
 import { Dexie } from "dexie";
 import { log } from "../config";
+import { getTokenGetter } from "./tokenRegistry";
+
+function decodeJwtExp(token) {
+  try {
+    var parts = token.split(".");
+    if (parts.length !== 3) return null;
+    var payload = JSON.parse(atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")));
+    return typeof payload.exp === "number" ? payload.exp : null;
+  } catch (_) {
+    return null;
+  }
+}
 
 export const syncProtocol = function () {
   log("Initializing syncProtocol");
   // Constants:
   var RECONNECT_DELAY = 5000; // Reconnect delay in case of errors such as network down.
+  var TOKEN_REFRESH_BUFFER = 60; // Refresh token this many seconds before exp
 
   Dexie.Syncable.registerSyncProtocol("websocket", {
     sync: function (
@@ -24,13 +37,12 @@ export const syncProtocol = function () {
       // The following vars are needed because we must know which callback to ack when server sends it's ack to us.
       var requestId = 0;
       var acceptCallbacks = {};
+      var refreshTimer = null;
 
       // Connect the WebSocket to given url:
       log("Connecting to", url)
       var ws = new WebSocket(url);
 
-      // console.log("ws OPTIONS", options);
-
       // sendChanges() method:
       function sendChanges(changes, baseRevision, partial, onChangesAccepted) {
         log("sendChanges", changes.length, baseRevision);
@@ -62,26 +74,72 @@ export const syncProtocol = function () {
 
 
 
-      // When WebSocket opens, send our changes to the server.
-      ws.onopen = function (event) {
-        // Initiate this socket connection by sending our clientIdentity. If we dont have a clientIdentity yet,
-        // server will call back with a new client identity that we should use in future WebSocket connections.
-        
-        // send the schema to the server
-        log("Opening socket - sending clientIdentity", context.clientIdentity);
-        ws.send(
-          JSON.stringify({
-            type: "clientIdentity",
-            clientIdentity: context.clientIdentity || null,
-            authToken: options.authToken,
-            schema: options.schema
-          }),
-        );
+      function clearRefreshTimer() {
+        if (refreshTimer) {
+          clearTimeout(refreshTimer);
+          refreshTimer = null;
+        }
+      }
+
+      // Resolve the getToken function from the module-level registry.
+      // It's stored there (not in options) because dexie-syncable serializes
+      // options into IndexedDB, and functions can't survive structured clone.
+      function resolveGetToken() {
+        var fn = getTokenGetter(url);
+        if (!fn) throw new Error("No token getter registered for " + url);
+        return fn;
+      }
 
+      // Schedule a proactive token refresh before the JWT expires.
+      // Sends a tokenUpdate message on the existing WebSocket so the
+      // server can accept the new token without dropping the connection.
+      function scheduleTokenRefresh(tokenStr) {
+        clearRefreshTimer();
+        var exp = decodeJwtExp(tokenStr);
+        if (!exp) return;
+        var msUntilRefresh = (exp - TOKEN_REFRESH_BUFFER) * 1000 - Date.now();
+        if (msUntilRefresh <= 0) return;
+        log("Scheduling proactive token refresh in", Math.round(msUntilRefresh / 1000), "s");
+        refreshTimer = setTimeout(async function () {
+          try {
+            var newToken = await resolveGetToken()({ forceRefresh: true });
+            if (ws.readyState === WebSocket.OPEN) {
+              log("Sending tokenUpdate on existing WebSocket");
+              ws.send(JSON.stringify({ type: "tokenUpdate", authToken: newToken }));
+              scheduleTokenRefresh(newToken);
+            }
+          } catch (err) {
+            log("Proactive token refresh failed (non-fatal):", err);
+          }
+        }, msUntilRefresh);
+      }
+
+      // When WebSocket opens, get a fresh token and send our identity to the server.
+      // This runs on every open, including reconnects after ERROR_WILL_RETRY,
+      // so each attempt gets a fresh token via getToken().
+      ws.onopen = async function (event) {
+        try {
+          var token = await resolveGetToken()();
+          log("Opening socket - sending clientIdentity", context.clientIdentity);
+          ws.send(
+            JSON.stringify({
+              type: "clientIdentity",
+              clientIdentity: context.clientIdentity || null,
+              authToken: token,
+              schema: options.schema
+            }),
+          );
+          scheduleTokenRefresh(token);
+        } catch (err) {
+          log("Failed to get token for WebSocket:", err);
+          ws.close();
+          onError("Authentication failed: " + (err.message || err), RECONNECT_DELAY);
+        }
       };
 
       // If network down or other error, tell the framework to reconnect again in some time:
       ws.onerror = function (event) {
+        clearRefreshTimer();
         ws.close();
         log("ws.onerror", event);
         onError(event?.message, RECONNECT_DELAY);
@@ -89,7 +147,7 @@ export const syncProtocol = function () {
 
       // If socket is closed (network disconnected), inform framework and make it reconnect
       ws.onclose = function (event) {
-        // console.log('🙅 ws.onclose', event)
+        clearRefreshTimer();
         onError("Socket closed: " + event.reason, RECONNECT_DELAY);
       };
 
@@ -114,7 +172,7 @@ export const syncProtocol = function () {
           //     partial: true if server has additionalChanges to send. False if these changes were the last known. (applicable if type="changes")
           // }
           var requestFromServer = JSON.parse(event.data);
-          log("requestFromServer", requestFromServer, { acceptCallback, isFirstRound });
+          log("requestFromServer", requestFromServer, { isFirstRound });
 
           if (requestFromServer.type == "clientIdentity") {
             context.clientIdentity = requestFromServer.clientIdentity;
@@ -151,8 +209,8 @@ export const syncProtocol = function () {
                     onChangesAccepted,
                   );
                 },
-                // Specify a disconnect function that will close our socket so that we dont continue to monitor changes.
                 disconnect: function () {
+                  clearRefreshTimer();
                   ws.close();
                 },
               });
@@ -164,9 +222,13 @@ export const syncProtocol = function () {
             acceptCallback(); // Tell framework that server has acknowledged the changes sent.
             delete acceptCallbacks[requestId.toString()];
           } else if (requestFromServer.type == "error") {
-            var requestId = requestFromServer.requestId;
             ws.close();
-            onError(requestFromServer.message, Infinity); // Don't reconnect - an error in application level means we have done something wrong.
+            if (requestFromServer.code === "TOKEN_EXPIRED" || requestFromServer.code === "UNAUTHORIZED") {
+              log("Auth error from server, will reconnect with fresh token:", requestFromServer.message);
+              onError(requestFromServer.message, RECONNECT_DELAY);
+            } else {
+              onError(requestFromServer.message, Infinity);
+            }
           } else {
             log("unknown message", requestFromServer);
             ws.close();

package/src/sync/tokenRegistry.ts

@@ -0,0 +1,20 @@
+/**
+ * Module-level registry for token getter functions, keyed by WebSocket URL.
+ *
+ * dexie-syncable serializes the `options` object into IndexedDB via
+ * structured clone, which cannot handle functions. This registry keeps
+ * the getToken function out of `options` so it survives serialization
+ * while remaining accessible to the sync protocol on every (re)connect.
+ */
+
+type GetTokenFn = (options?: { forceRefresh?: boolean }) => Promise<string>
+
+const registry = new Map<string, GetTokenFn>()
+
+export function setTokenGetter(url: string, fn: GetTokenFn): void {
+    registry.set(url, fn)
+}
+
+export function getTokenGetter(url: string): GetTokenFn | undefined {
+    return registry.get(url)
+}

package/src/updater/updateMigrations.ts

@@ -1,12 +1,12 @@
 import { BasicStorage } from '../utils/storage'
 import { Migration } from './versionUpdater'
-
+import { log } from '../config'
 
 export const addMigrationTimestamp: Migration = {
-  fromVersion: '0.6.0', 
+  fromVersion: '0.6.0',
   toVersion: '0.7.0',
   async migrate(storage: BasicStorage) {
-    console.log('Running test migration')
+    log('Running migration 0.6.0 → 0.7.0')
     storage.set('test_migration', 'true')
   }
 }

package/src/updater/versionUpdater.ts

@@ -1,4 +1,5 @@
 import { BasicStorage } from '../utils/storage'
+import { log } from '../config'
 
 export interface VersionInfo {
   version: string
@@ -53,7 +54,7 @@ export class VersionUpdater {
     // Run migrations
     for (const migration of migrationsToRun) {
       try {
-        console.log(`Running migration from ${migration.fromVersion} to ${migration.toVersion}`)
+        log(`Running migration from ${migration.fromVersion} to ${migration.toVersion}`)
         await migration.migrate(this.storage)
       } catch (error) {
         console.error(`Migration failed from ${migration.fromVersion} to ${migration.toVersion}:`, error)
@@ -89,18 +90,10 @@ export class VersionUpdater {
 
   private getMigrationsToRun(fromVersion: string, toVersion: string): Migration[] {
     return this.migrations.filter(migration => {
-      // Migration should run if we're crossing the version boundary
-      // i.e., stored version is less than migration.toVersion AND current version is >= migration.toVersion
       const storedLessThanMigrationTo = this.compareVersions(fromVersion, migration.toVersion) < 0
       const currentGreaterThanOrEqualMigrationTo = this.compareVersions(toVersion, migration.toVersion) >= 0
-      
-      console.log(`Checking migration ${migration.fromVersion} → ${migration.toVersion}:`)
-      console.log(`  stored ${fromVersion} < migration.to ${migration.toVersion}: ${storedLessThanMigrationTo}`)
-      console.log(`  current ${toVersion} >= migration.to ${migration.toVersion}: ${currentGreaterThanOrEqualMigrationTo}`)
-      
       const shouldRun = storedLessThanMigrationTo && currentGreaterThanOrEqualMigrationTo
-      console.log(`  Should run: ${shouldRun}`)
-      
+      log(`Migration ${migration.fromVersion} → ${migration.toVersion}: shouldRun=${shouldRun}`)
       return shouldRun
     })
   }

package/src/utils/normalizeClientId.ts

@@ -0,0 +1,22 @@
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * Normalize a project_id / client_id to the canonical did:web format
+ * before sending it to the PDS.
+ *
+ * - did:web:... -> passthrough (already canonical)
+ * - bare UUID   -> did:web:{adminHostname}:projects:{hex}
+ * - "self"      -> passthrough
+ */
+export function normalizeClientId(projectId: string, adminHostname: string = 'api.basic.tech'): string {
+  if (!projectId) return projectId
+  if (projectId === 'self') return projectId
+  if (projectId.startsWith('did:')) return projectId
+
+  if (UUID_RE.test(projectId)) {
+    const hex = projectId.replace(/-/g, '').toLowerCase()
+    return `did:web:${adminHostname}:projects:${hex}`
+  }
+
+  return projectId
+}

package/src/utils/resolveDid.ts

@@ -0,0 +1,101 @@
+export type ResolvedDid = {
+  did: string
+  handle?: string
+  didDocument: Record<string, unknown>
+  pdsUrl: string
+  authorization_endpoint: string
+  token_endpoint: string
+  userinfo_endpoint: string
+}
+
+/**
+ * Convert a did:web DID to the HTTPS URL where its DID document lives.
+ *
+ * did:web:pds.basic.id:did:abc123 -> https://pds.basic.id/did/abc123/did.json
+ * did:web:example.com             -> https://example.com/.well-known/did.json
+ */
+export function resolveDidWebUrl(did: string): string | null {
+  if (!did.startsWith('did:web:')) return null
+
+  const rest = did.slice(8) // strip 'did:web:'
+  if (!rest) return null
+  const parts = rest.split(':')
+
+  // Decode the hostname (first part, may contain %3A for port)
+  const hostname = parts[0]!.replace(/%3A/gi, ':')
+
+  if (parts.length === 1) {
+    return `https://${hostname}/.well-known/did.json`
+  }
+
+  const pathParts = parts.slice(1).map(p => decodeURIComponent(p))
+  return `https://${hostname}/${pathParts.join('/')}/did.json`
+}
+
+/**
+ * Given a DID document, extract PDS URL and discover OAuth endpoints.
+ */
+async function resolveFromDocument(did: string, didDocument: Record<string, unknown>): Promise<ResolvedDid> {
+  const services = didDocument.service as Array<{ id: string; type: string; serviceEndpoint: string }> | undefined
+  const pdsService = services?.find(
+    (s) => s.id === '#basic_pds' || s.id === `${did}#basic_pds`
+  )
+  if (!pdsService) {
+    throw new Error(`DID document has no #basic_pds service entry`)
+  }
+  const pdsUrl = pdsService.serviceEndpoint.replace(/\/+$/, '')
+
+  const oauthRes = await fetch(`${pdsUrl}/auth/.well-known/openid-configuration`)
+  if (!oauthRes.ok) {
+    throw new Error(`Failed to fetch OpenID configuration from ${pdsUrl}: ${oauthRes.status}`)
+  }
+  const oauth = await oauthRes.json()
+
+  return {
+    did,
+    didDocument,
+    pdsUrl,
+    authorization_endpoint: oauth.authorization_endpoint,
+    token_endpoint: oauth.token_endpoint,
+    userinfo_endpoint: oauth.userinfo_endpoint,
+  }
+}
+
+/**
+ * Fetch a DID document by DID, extract the PDS URL, and discover OAuth endpoints.
+ */
+export async function resolveDid(did: string): Promise<ResolvedDid> {
+  const url = resolveDidWebUrl(did)
+  if (!url) {
+    throw new Error(`Unsupported DID method: ${did}`)
+  }
+
+  const didRes = await fetch(url)
+  if (!didRes.ok) {
+    throw new Error(`Failed to fetch DID document at ${url}: ${didRes.status}`)
+  }
+  const didDocument = await didRes.json()
+
+  return resolveFromDocument(did, didDocument)
+}
+
+/**
+ * Resolve a handle (e.g. "alice.basic.id") to a DID and discover PDS + OAuth endpoints.
+ *
+ * Fetches https://{handle}/.well-known/did.json per the did:web spec.
+ */
+export async function resolveHandle(handle: string): Promise<ResolvedDid> {
+  const res = await fetch(`https://${handle}/.well-known/did.json`)
+  if (!res.ok) {
+    throw new Error(`Handle resolution failed for ${handle}: ${res.status}`)
+  }
+  const didDocument = await res.json()
+  const did = didDocument.id as string
+  if (!did) {
+    throw new Error(`Handle response has no 'id' field`)
+  }
+
+  const resolved = await resolveFromDocument(did, didDocument)
+  resolved.handle = handle
+  return resolved
+}

package/src/utils/schema.ts

@@ -30,8 +30,6 @@ export async function getSchemaStatus(schema: any): Promise<{
         }
     })
 
-    console.log('latestSchema', latestSchema)
-
     if (!latestSchema.version) {
         return { 
             valid: false, 
@@ -105,11 +103,12 @@ export async function validateAndCheckSchema(schema: any): Promise<{
         }
     }
 
-    let schemaStatus = { valid: false }
+    let schemaStatus: { valid: boolean, status?: string, latest?: any } = { valid: false }
     if (schema.version !== 0) {
         schemaStatus = await getSchemaStatus(schema)
         log('schemaStatus', schemaStatus)
-    } else { 
+    } else {
+        schemaStatus = { valid: false, status: 'unpublished' }
         log("schema not published - at version 0")
     }
 

package/src/utils/storage.ts

@@ -25,7 +25,10 @@ export const STORAGE_KEYS = {
     AUTH_STATE: 'basic_auth_state',
     REDIRECT_URI: 'basic_redirect_uri',
     SERVER_URL: 'basic_server_url',
-    DEBUG: 'basic_debug'
+    PDS_ENDPOINTS: 'basic_pds_endpoints',
+    LAST_CONNECT_REPORT: 'basic_last_connect_report',
+    DEBUG: 'basic_debug',
+    CODE_VERIFIER: 'basic_code_verifier'
 } as const
 
 export function getCookie(name: string): string {