@synthigy/sdk 0.1.2 → 0.2.0

package/src/browser-login.js

@@ -0,0 +1,309 @@
+/**
+ * Browser login as a PUBLIC client: authorization code + PKCE, silent renew
+ * through a hidden iframe, tokens in memory only. The same flow Synthigy's own
+ * tools use (the Clojure SDK's `synthigy.client.login`).
+ *
+ * The server-side, confidential flow is `client.login` (login.js). This one
+ * holds no secret: the code exchange is authenticated by the PKCE verifier.
+ * Nothing touches localStorage — only the in-flight login (verifier, nonce,
+ * return path) sits in sessionStorage between the redirect and the callback.
+ * A reload restores the session through silent renew, which rides the
+ * engine's own session cookie.
+ */
+
+import { pkce, decodeJwtPayload } from './login.js'
+
+const PENDING_PREFIX = 'synthigy.login:'
+const PENDING_TTL_MS = 5 * 60_000
+const MESSAGE_SOURCE = 'synthigy-login'
+
+function randomToken(bytes) {
+  let binary = ''
+  for (const b of globalThis.crypto.getRandomValues(new Uint8Array(bytes))) binary += String.fromCharCode(b)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+/** The authorization response `href` carries, or null. */
+export function callbackParams(href) {
+  const q = new URL(href).searchParams
+  const state = q.get('state')
+  const code = q.get('code')
+  const error = q.get('error')
+  if (!state || !(code || error)) return null
+  return { state, code, error, errorDescription: q.get('error_description') }
+}
+
+/**
+ * Call first thing on the silent-redirect page. True when this window is a
+ * renewal iframe and has handed its URL to the parent — stop there.
+ */
+export function silentCallback() {
+  const w = globalThis.window
+  if (!w || w === w.parent || !callbackParams(globalThis.location.href)) return false
+  w.parent.postMessage({ source: MESSAGE_SOURCE, url: globalThis.location.href }, globalThis.location.origin)
+  return true
+}
+
+export function createBrowserLogin(config = {}, { SynthigyError }) {
+  const { endpoint, clientId, redirectUri } = config
+  if (!endpoint || !clientId || !redirectUri) {
+    throw new SynthigyError('createBrowserLogin needs endpoint, clientId and redirectUri', 'CONFIG_ERROR')
+  }
+  const cfg = {
+    scope: 'openid profile',
+    automaticSilentRenew: true,
+    loadUserInfo: false,
+    silentTimeoutMs: 10_000,
+    expiringSeconds: 60,
+    silentRedirectUri: redirectUri,
+    postLogoutRedirectUri: redirectUri,
+    ...config,
+    endpoint: endpoint.replace(/\/+$/, ''),
+  }
+  const doFetch = cfg.fetch ?? globalThis.fetch.bind(globalThis)
+  const storage = cfg.storage ?? globalThis.sessionStorage
+
+  let tokens = null
+  let user = null
+  let renewal = null
+  let timers = []
+  const listeners = new Map()
+
+  const emit = (event, payload) => {
+    for (const f of listeners.get(event) ?? []) {
+      try { f(payload) } catch (e) { console.warn('synthigy browser login listener error:', e) }
+    }
+  }
+
+  const authorizeUrl = (request) => {
+    const params = new URLSearchParams()
+    for (const [k, v] of [
+      ['response_type', 'code'],
+      ['client_id', clientId],
+      ['redirect_uri', request.redirectUri],
+      ['scope', cfg.scope],
+      ['state', request.state],
+      ['nonce', request.nonce],
+      ['code_challenge', request.codeChallenge],
+      ['code_challenge_method', 'S256'],
+      ['audience', cfg.audience],
+      ['prompt', request.prompt],
+    ]) if (v != null) params.append(k, v)
+    return `${cfg.endpoint}/oauth/authorize?${params}`
+  }
+
+  const startRequest = async (uri, prompt) => {
+    const { codeVerifier, codeChallenge } = await pkce()
+    return { redirectUri: uri, prompt, state: randomToken(24), nonce: randomToken(24), codeVerifier, codeChallenge }
+  }
+
+  const putPending = (request, returnTo) => storage.setItem(PENDING_PREFIX + request.state, JSON.stringify({
+    redirectUri: request.redirectUri, nonce: request.nonce, codeVerifier: request.codeVerifier,
+    returnTo, createdAt: Date.now(),
+  }))
+
+  const takePending = (state) => {
+    const key = PENDING_PREFIX + state
+    const raw = storage.getItem(key)
+    storage.removeItem(key)
+    if (!raw) return null
+    const pending = JSON.parse(raw)
+    return pending.createdAt > Date.now() - PENDING_TTL_MS ? pending : null
+  }
+
+  const stripCallback = () => {
+    const l = globalThis.location
+    globalThis.history.replaceState(null, '', l.pathname + l.hash)
+  }
+
+  const exchange = async (code, { redirectUri: uri, codeVerifier }) => {
+    const resp = await doFetch(`${cfg.endpoint}/oauth/token`, {
+      method: 'POST',
+      credentials: 'omit',
+      headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code', code, redirect_uri: uri,
+        client_id: clientId, code_verifier: codeVerifier,
+      }).toString(),
+    })
+    const text = await resp.text()
+    if (!resp.ok) {
+      throw new SynthigyError(`authorization-code exchange failed (${resp.status})`,
+        'LOGIN_EXCHANGE_FAILED', text, { status: resp.status })
+    }
+    return JSON.parse(text)
+  }
+
+  const clearTimers = () => { timers.forEach(clearTimeout); timers = [] }
+
+  const schedule = (expiresAt) => {
+    clearTimers()
+    const now = Date.now()
+    timers = [
+      setTimeout(() => {
+        emit('accessTokenExpiring')
+        if (cfg.automaticSilentRenew) api.renew().catch(() => {})
+      }, Math.max(0, expiresAt - cfg.expiringSeconds * 1000 - now)),
+      setTimeout(() => emit('accessTokenExpired'), Math.max(0, expiresAt - now)),
+    ]
+  }
+
+  const userInfo = async (accessToken) => {
+    const resp = await doFetch(`${cfg.endpoint}/oauth/userinfo`, {
+      method: 'GET',
+      credentials: 'omit',
+      headers: { Accept: 'application/json', Authorization: `Bearer ${accessToken}` },
+    })
+    const text = await resp.text()
+    if (!resp.ok) {
+      throw new SynthigyError(`userinfo request failed (${resp.status})`, 'USERINFO_FAILED', text,
+        { status: resp.status })
+    }
+    return JSON.parse(text)
+  }
+
+  const accept = async (tokenResponse, nonce) => {
+    const claims = decodeJwtPayload(tokenResponse.id_token)
+    if (!claims) {
+      throw new SynthigyError('token response carried no readable id_token — request the openid scope',
+        'LOGIN_EXCHANGE_FAILED')
+    }
+    if (claims.nonce !== nonce) {
+      throw new SynthigyError('id_token nonce does not match the one this login started with',
+        'LOGIN_NONCE_MISMATCH')
+    }
+    const info = cfg.loadUserInfo ? await userInfo(tokenResponse.access_token) : null
+    if (info && info.sub !== claims.sub) {
+      throw new SynthigyError('userinfo sub does not match the id_token', 'USERINFO_SUB_MISMATCH')
+    }
+    tokens = tokenResponse
+    user = { ...claims, ...info }
+    schedule(Date.now() + 1000 * (tokenResponse.expires_in ?? 300))
+    emit('userLoaded', user)
+    return user
+  }
+
+  const authorizationError = ({ error, errorDescription }) =>
+    new SynthigyError(errorDescription || error, error)
+
+  const silentFrame = (request) => new Promise((resolve, reject) => {
+    const frame = globalThis.document.createElement('iframe')
+    const origin = new URL(cfg.silentRedirectUri).origin
+    frame.style.cssText = 'position:absolute;width:0;height:0;border:0;visibility:hidden'
+    let timer
+    const cleanup = () => {
+      clearTimeout(timer)
+      globalThis.window.removeEventListener('message', onMessage)
+      frame.remove()
+    }
+    const onMessage = (e) => {
+      if (e.origin !== origin || e.source !== frame.contentWindow || e.data?.source !== MESSAGE_SOURCE) return
+      cleanup()
+      const params = callbackParams(e.data.url)
+      if (params?.state === request.state) resolve(params)
+      else reject(new SynthigyError('silent renew answered with a foreign state', 'LOGIN_STATE_UNKNOWN'))
+    }
+    timer = setTimeout(() => {
+      cleanup()
+      reject(new SynthigyError('silent renew timed out', 'SILENT_TIMEOUT'))
+    }, cfg.silentTimeoutMs)
+    globalThis.window.addEventListener('message', onMessage)
+    frame.src = authorizeUrl(request)
+    globalThis.document.body.appendChild(frame)
+  })
+
+  const api = {
+    get user() { return user },
+    get token() { return tokens?.access_token ?? null },
+
+    /** Subscribe to userLoaded, userUnloaded, accessTokenExpiring, accessTokenExpired or silentRenewError. */
+    on(event, f) {
+      if (!listeners.has(event)) listeners.set(event, new Set())
+      listeners.get(event).add(f)
+      return () => listeners.get(event).delete(f)
+    },
+
+    /** True when the current URL is an authorization response. */
+    isCallback: () => callbackParams(globalThis.location.href) !== null,
+
+    /** Redirect to the login page. `prompt: 'none'` comes straight back when a session is alive. */
+    async start({ prompt, returnTo } = {}) {
+      const l = globalThis.location
+      const request = await startRequest(redirectUri, prompt)
+      putPending(request, returnTo ?? l.pathname + l.search + l.hash)
+      l.assign(authorizeUrl(request))
+    },
+
+    /** Finish the login the current URL returns from: `{ user, returnTo }`, or null when it carries none. */
+    async complete() {
+      const params = callbackParams(globalThis.location.href)
+      if (!params) return null
+      const pending = takePending(params.state)
+      stripCallback()
+      if (!pending) {
+        throw new SynthigyError('unknown or expired login state: already consumed, timed out, or started in another tab',
+          'LOGIN_STATE_UNKNOWN')
+      }
+      if (!params.code) throw authorizationError(params)
+      const tokenResponse = await exchange(params.code, pending)
+      return { user: await accept(tokenResponse, pending.nonce), returnTo: pending.returnTo }
+    },
+
+    /** Drop the login the current URL returns from (the user cancelled): `{ returnTo }` or null. */
+    cancel() {
+      const params = callbackParams(globalThis.location.href)
+      if (!params) return null
+      stripCallback()
+      const pending = takePending(params.state)
+      return pending ? { returnTo: pending.returnTo } : null
+    },
+
+    /** Silent renew through a hidden iframe (prompt=none); one renewal at a time. */
+    renew() {
+      if (renewal) return renewal
+      renewal = (async () => {
+        const request = await startRequest(cfg.silentRedirectUri, 'none')
+        const params = await silentFrame(request)
+        if (!params.code) throw authorizationError(params)
+        return await accept(await exchange(params.code, request), request.nonce)
+      })()
+        .catch((e) => { emit('silentRenewError', e); throw e })
+        .finally(() => { renewal = null })
+      return renewal
+    },
+
+    /** Forget the tokens here without ending the server session. */
+    removeUser() {
+      clearTimers()
+      tokens = null
+      user = null
+      emit('userUnloaded')
+    },
+
+    /** End the server session and go to postLogoutRedirectUri. */
+    logout() {
+      const params = new URLSearchParams()
+      if (tokens?.id_token) params.append('id_token_hint', tokens.id_token)
+      params.append('post_logout_redirect_uri', cfg.postLogoutRedirectUri)
+      api.removeUser()
+      globalThis.location.assign(`${cfg.endpoint}/oauth/logout?${params}`)
+    },
+
+    /**
+     * For `createClient({ tokenProvider })`. A 401 clears → starts a renewal,
+     * and the retried request waits for it.
+     */
+    tokenProvider() {
+      return {
+        async getToken() {
+          if (renewal) await renewal.catch(() => {})
+          return api.token
+        },
+        clear() {
+          api.renew().catch(() => {})
+        },
+      }
+    },
+  }
+  return api
+}

package/src/index.d.ts

@@ -294,11 +294,16 @@ export interface Schema {
  *
  * Client-side (no server round trip):
  *   NO_TOKEN — no token source configured; see ClientConfig.
+ *   NO_LOGIN_STORE — createClient({ loginStore }) was never given one.
+ *   LOGIN_REQUIRES_CONFIDENTIAL_CLIENT — login needs clientId + clientSecret.
+ *   LOGIN_STATE_UNKNOWN, LOGIN_NONCE_MISMATCH, LOGIN_EXCHANGE_FAILED — see client.login.
  */
 export type SynthigyErrorCode =
   | 'UNAUTHORIZED' | 'CLIENT_NOT_FOUND' | 'CLIENT_INACTIVE'
   | 'PUBLIC_CLIENT_FORBIDDEN' | 'NOT_TRUSTED' | 'USER_NOT_FOUND'
   | 'FORBIDDEN' | 'NO_TOKEN'
+  | 'NO_LOGIN_STORE' | 'LOGIN_REQUIRES_CONFIDENTIAL_CLIENT'
+  | 'LOGIN_STATE_UNKNOWN' | 'LOGIN_NONCE_MISMATCH' | 'LOGIN_EXCHANGE_FAILED'
   | 'INVALID_BODY' | 'NO_OPERATIONS' | 'BAD_OP' | 'MISSING_ENTITY'
   | 'BAD_ARGS_SHAPE'
   | 'UNKNOWN_OP' | 'UNKNOWN_ENTITY' | 'UNKNOWN_ATTRIBUTE' | 'UNKNOWN_OPERATOR'
@@ -321,7 +326,8 @@ export class SynthigyError extends Error {
 // ============================================================================
 
 export interface ClientConfig {
-  endpoint: string
+  /** Synthigy base URL. Defaults to `$SYNTHIGY_ENDPOINT` (set by `synthigy exec`). */
+  endpoint?: string
   /** OAuth client ID — required with clientSecret for client credentials */
   clientId?: string
   clientSecret?: string
@@ -332,6 +338,12 @@ export interface ClientConfig {
    * with no source at all it throws SynthigyError{code: 'NO_TOKEN'}.
    */
   token?: string
+  /**
+   * Caller-owned token source, checked before every other option. `clear()`
+   * is called on a 401 before the single retry; `createBrowserLogin()`'s
+   * `tokenProvider()` renews there.
+   */
+  tokenProvider?: TokenProvider
   scope?: string
   /**
    * Default client_credentials audience, applied to every mint this client
@@ -368,6 +380,131 @@ export interface ClientConfig {
    * Pass `undici.fetch` with a shared `Agent` for pooled connections in Node.
    */
   fetch?: typeof globalThis.fetch
+  /**
+   * Where in-flight logins live between `login.start()` and the callback.
+   * Required to use `client.login` at all — without one, every call throws
+   * `NO_LOGIN_STORE` rather than silently keeping state in one process.
+   * `MemoryLoginStore` is the single-process dev option.
+   */
+  loginStore?: LoginStore
+}
+
+// ============================================================================
+// Login — OIDC authorization-code + PKCE
+// ============================================================================
+
+/** One login in flight: everything the callback needs to finish it. */
+export interface PendingLogin {
+  codeVerifier: string
+  nonce: string
+  returnTo: string
+  createdAt: number
+}
+
+/**
+ * The one piece of protocol state the SDK cannot hold for you.
+ *
+ * `take` is one-shot: it must return the login AND remove it, so a replayed
+ * callback finds nothing. Both methods may be sync or async.
+ */
+export interface TokenProvider {
+  getToken(audience?: string): string | null | Promise<string | null>
+  clear(): void
+}
+
+export interface BrowserLoginConfig {
+  endpoint: string
+  clientId: string
+  /** The page that finishes the login (calls `complete()`), registered on the client. */
+  redirectUri: string
+  /** Page the renewal iframe lands on; default `redirectUri`. It must call `silentCallback()` first. */
+  silentRedirectUri?: string
+  postLogoutRedirectUri?: string
+  /** Default 'openid profile'. */
+  scope?: string
+  audience?: string
+  /** Renew silently shortly before expiry (default true). */
+  automaticSilentRenew?: boolean
+  /** Merge /oauth/userinfo into `user` after each login and renewal (default false) — the profile (name, email) lives there. */
+  loadUserInfo?: boolean
+  /** Seconds before expiry that renewal starts (default 60). */
+  expiringSeconds?: number
+  silentTimeoutMs?: number
+  fetch?: typeof globalThis.fetch
+  /** Where the in-flight login waits for the callback (default sessionStorage). */
+  storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>
+}
+
+export type BrowserLoginEvent =
+  'userLoaded' | 'userUnloaded' | 'accessTokenExpiring' | 'accessTokenExpired' | 'silentRenewError'
+
+export interface BrowserLogin {
+  /** id_token claims of the logged-in user (`sub`, `xid`, …), or null. */
+  readonly user: Record<string, unknown> | null
+  readonly token: string | null
+  on(event: BrowserLoginEvent, listener: (payload?: unknown) => void): () => void
+  isCallback(): boolean
+  /** Redirect to the login page; `prompt: 'none'` returns at once when a session is alive. */
+  start(opts?: { prompt?: 'none' | 'login'; returnTo?: string }): Promise<void>
+  /** Finish the login the current URL returns from, or null when it carries none. */
+  complete(): Promise<{ user: Record<string, unknown>; returnTo: string } | null>
+  /** The user cancelled on the IdP: drop the pending login. */
+  cancel(): { returnTo: string } | null
+  renew(): Promise<Record<string, unknown>>
+  removeUser(): void
+  logout(): void
+  tokenProvider(): TokenProvider
+}
+
+/** Browser login as a public client: PKCE, silent renew, tokens in memory. */
+export function createBrowserLogin(config: BrowserLoginConfig): BrowserLogin
+
+/** Call first on the silent-redirect page; true when this window was a renewal iframe and answered it. */
+export function silentCallback(): boolean
+
+export interface LoginStore {
+  put(state: string, login: PendingLogin): void | Promise<void>
+  take(state: string): PendingLogin | null | Promise<PendingLogin | null>
+}
+
+/** In-memory `LoginStore`. Single process only — see the class docstring. */
+export class MemoryLoginStore implements LoginStore {
+  constructor(opts?: { ttlMs?: number })
+  put(state: string, login: PendingLogin): void
+  take(state: string): PendingLogin | null
+}
+
+export interface LoginStartOpts {
+  /** URL on YOUR server the IdP redirects back to; must be registered on the client. */
+  redirectUri: string
+  /** Where to send the visitor once login finishes. Default `'/'`. */
+  returnTo?: string
+  /** Default `'openid'` — the scope that names the user. */
+  scope?: string
+  /** Browser-reachable engine URL, when it differs from the server-side one. */
+  publicEndpoint?: string
+}
+
+export interface LoginCompleteOpts {
+  code: string
+  state: string
+  redirectUri: string
+}
+
+export interface LoginTokens {
+  access_token: string
+  id_token?: string
+  refresh_token?: string
+  token_type?: string
+  scope?: string
+  expires_in?: number
+}
+
+export interface LoginResult {
+  /** Straight out of the id_token — no /data round-trip. */
+  user: { xid: string | null; name: string | null; scopes: string[] }
+  tokens: LoginTokens
+  returnTo: string
 }
 
 // ============================================================================
@@ -566,6 +703,19 @@ export class SynthigyClient {
     since(opts?: HistorySinceOpts): Promise<HistoryEvent[]>
   }
 
+  // ── Login — OIDC authorization-code + PKCE ───────────────────────────────
+
+  login: {
+    /** Begin a login; redirect the browser to the returned URL. */
+    start(opts: LoginStartOpts): Promise<{ url: string }>
+
+    /** Finish a login from the callback's `code` + `state`. */
+    complete(opts: LoginCompleteOpts): Promise<LoginResult>
+
+    /** Drop an in-flight login and recover its `returnTo`; null when unknown. */
+    cancel(state: string | null | undefined): Promise<{ returnTo: string } | null>
+  }
+
   /** Fetch the IAM-filtered model schema via `GET /schema`. Pass entity names to filter. */
   schema(entities?: string[]): Promise<Schema>
 
@@ -578,6 +728,17 @@ export class SynthigyClient {
     op?: 'search' | 'get' | 'slice' | 'purge'
   }): Promise<LintDiagnostic[]>
 
+  /**
+   * Compile an XSQL source to the wire operation the engine would execute
+   * (`POST /compile`), without executing it. `params` bind exactly as on
+   * `query`, so the result IS what the engine receives — edit it and send
+   * it through `exec`.
+   */
+  compile(source: string, opts?: {
+    params?: Record<string, unknown>
+    op?: 'search' | 'get' | 'slice' | 'purge'
+  }): Promise<Operation>
+
   /**
    * Mint a one-time account-claim link via `POST /oauth/onboard`.
    * Confidential client whose principal administers the account — RBAC
@@ -1027,14 +1188,16 @@ export function rel(selections: Selection, args?: Args, alias?: string): Relatio
 export const op: {
   search(entity: string, args: Args | undefined, selection: Selection): Operation
   get(entity: string, args: Record<string, unknown>, selection: Selection): Operation
-  sync(entity: string, data: Record<string, unknown>, returning?: boolean): Operation
-  stack(entity: string, data: Record<string, unknown>, returning?: boolean): Operation
+  sync(entity: string, data: Record<string, unknown> | Record<string, unknown>[], returning?: boolean): Operation
+  stack(entity: string, data: Record<string, unknown> | Record<string, unknown>[], returning?: boolean): Operation
   slice(entity: string, args: Record<string, unknown>, selection?: Selection): Operation
   delete(entity: string, data: Record<string, unknown>): Operation
   purge(entity: string, args: Args | undefined, selection?: Selection): Operation
   searchTree(entity: string, on: string, args: Args | undefined, selection: Selection): Operation
   getTree(entity: string, root: string, on: string, selection: Selection): Operation
   sqlTemplate(template: string, params?: Record<string, unknown> | unknown[], opts?: { cached?: boolean }): Operation
+  /** An XSQL read, for `exec` batches; `verb` names the op a bare body runs as (default `search`). */
+  query(xsql: string, params?: Record<string, unknown>, verb?: string): Operation
   deployedModel(): Operation
   runtimeModel(): Operation
   deploy(exportContents: string): Operation
@@ -1074,7 +1237,7 @@ export function composeForest<T extends Record<string, unknown>>(
 // Factory
 // ============================================================================
 
-export function createClient(config: ClientConfig): SynthigyClient
+export function createClient(config?: ClientConfig): SynthigyClient
 
 // ============================================================================
 // Single-client layer — connect once, call the bare verbs, no client threading.
@@ -1083,7 +1246,7 @@ export function createClient(config: ClientConfig): SynthigyClient
 // ============================================================================
 
 /** Install a module-wide default client (destroys any previous one). */
-export function connect(config: ClientConfig): SynthigyClient
+export function connect(config?: ClientConfig): SynthigyClient
 /** Destroy and uninstall the default client. No-op when not connected. */
 export function disconnect(): void
 /** The default client installed by `connect`, or null. */
@@ -1112,12 +1275,16 @@ export { _delete as delete }
 
 export const schema: SynthigyClient['schema']
 export const lint: SynthigyClient['lint']
+export const compile: SynthigyClient['compile']
+export const onboard: SynthigyClient['onboard']
+export const onboardComplete: SynthigyClient['onboardComplete']
 export const deploy: SynthigyClient['deploy']
 export const destroy: SynthigyClient['destroy']
 export const deployedModel: SynthigyClient['deployedModel']
 export const runtimeModel: SynthigyClient['runtimeModel']
 export const token: SynthigyClient['token']
 export function history(): SynthigyClient['history']
+export function login(): SynthigyClient['login']
 
 export const listen: SynthigyClient['listen']
 export const observe: SynthigyClient['observe']