Auth SDK (@zeq/auth)

The @zeq/auth package provides vanilla ES module, React, and Vue 3 bindings for Sign in with Zeq — the cross-domain PKCE authentication system built into Zeq OS.

npm install @zeq/auth

Full protocol documentation, REST API reference, and security details are in Sign in with Zeq.

---

Vanilla JavaScript

import { ZeqAuthClient } from '@zeq/auth';

const auth = new ZeqAuthClient({
  clientId: 'my-app-a1b2c3',
  authBase: 'https://auth.zeq.os',
  scope: 'identity vault:read',
});

// Restore previous session
auth.loadSession();

// Open PKCE popup
const { token, user } = await auth.connect();

// Authenticated fetch
const res = await auth.fetchWithAuth('/api/protected');

// Vault
const saved = await auth.readVault('https://myapp.example.com');
await auth.writeVault('https://myapp.example.com', { key: 'value' });

// Log out
auth.logout();

Same-origin login (no popup, equation sent directly):

import { auth } from '@zeq/auth'; // pre-built singleton, authBase: '/auth'

await auth.login('E = mc²');
await auth.register('E = mc²', 'Alice');

---

React

import { ZeqAuthProvider, useZeqAuth, ZeqSignInButton } from '@zeq/auth/react';

// Wrap your app
<ZeqAuthProvider
  clientId="my-app-a1b2c3"
  authBase="https://auth.zeq.os"
  scope="identity vault:read"
  protect>
  <App />
</ZeqAuthProvider>

function Profile() {
  const { user, loading, connect, logout, fetchWithAuth, readVault, writeVault } = useZeqAuth();

  if (loading) return <p>Loading…</p>;
  if (!user)   return <ZeqSignInButton />;

  return (
    <div>
      <p>Welcome, {user.displayName}</p>
      <ZeqSignInButton /> {/* renders "Signed in as … — Log out" when authenticated */}
    </div>
  );
}

ZeqAuthProvider props: clientId, authBase, scope, protect (auto-connect on expired session), autoConnect (connect on mount).

useZeqAuth() returns: user, token, loading, error, isAuthenticated, connect, logout, fetchWithAuth, readVault, writeVault.

---

Vue 3

// main.js
import ZeqAuth from '@zeq/auth/vue';

app.use(ZeqAuth, {
  clientId: 'my-app-a1b2c3',
  authBase: 'https://auth.zeq.os',
  scope: 'identity vault:read',
});

<script setup>
import { useZeqAuth, ZeqSignInButton } from '@zeq/auth/vue';

const { user, loading, connect, logout, fetchWithAuth } = useZeqAuth();
</script>

<template>
  <div v-if="loading">Loading…</div>
  <ZeqSignInButton v-else-if="!user" @success="console.log($event)" />
  <div v-else>{{ user.displayName }} <button @click="logout">Log out</button></div>
</template>

token, user, loading, and error are Vue readonly refs. The composable throws if called outside a component that has ZeqAuth installed via app.use().

---

Registering an App

Before using cross-domain PKCE you need a client_id. Use the SDK or curl:

// Requires an existing Zeq session token
const auth = new ZeqAuthClient({ authBase: 'https://auth.zeq.os' });
auth.saveSession(myToken, myUser);

const app = await auth.registerApp({
  appName: 'My App',
  redirectUris: ['https://myapp.example.com/callback'],
  scopes: ['identity', 'vault:read'],
});
// app.client_id  — use this everywhere
// app.client_secret — store securely, shown once only

Get a pre-built embed snippet for any registered app:

const snippet = await auth.getEmbedSnippet('my-app-a1b2c3');
// Returns the <script> tag HTML, ready to paste

See the Sign in with Zeq reference for the full REST API, scopes table, drop-in script tag usage, and security details.