@gaballahtech/seba 0.0.0-stage → 0.2.1

package/examples/node/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Node.js example: restore or start a login, read the user's profile, sign out.
+ *
+ * Prerequisites for the local Community Solid Server flow:
+ *
+ * 1. `npm run build` (the example imports the package through its self-reference).
+ * 2. A CSS instance on http://localhost:3000 with an account and a pod.
+ * 3. A Client ID Document served over http on loopback that publishes the redirect URI.
+ *
+ * Run:
+ *
+ * ```bash
+ * SEBA_CLIENT_ID=http://localhost:8443/client-id.jsonld \
+ * SEBA_REDIRECT_URI=http://localhost:3001/auth/callback \
+ * SEBA_ISSUER=http://localhost:3000 \
+ * WEBID=http://localhost:3000/alice/profile/card#me \
+ *   node examples/node/index.ts
+ * ```
+ *
+ * The redirect URI must be published verbatim in the Client ID Document and must use
+ * plain http on loopback (`127.0.0.1`, `::1` or `localhost`) because SEBA starts a
+ * temporary callback server there.
+ */
+
+import { exec } from "node:child_process";
+import { Seba } from "@gaballahtech/seba/node";
+
+const issuer = process.env["SEBA_ISSUER"] ?? "http://localhost:3000";
+const clientId = process.env["SEBA_CLIENT_ID"] ?? "http://localhost:8443/client-id.jsonld";
+const redirectUri = process.env["SEBA_REDIRECT_URI"] ?? "http://localhost:3001/auth/callback";
+const webId = process.env["WEBID"];
+
+const seba = new Seba({
+  clientId,
+  redirectUri,
+  openAuthorizationUrl(url) {
+    // Replace with the opener for your platform: `open` (macOS), `start` (Windows).
+    exec(`xdg-open "${url}"`, (error) => {
+      if (error !== null) {
+        console.error("Open this URL in a browser to continue:");
+        console.error(url);
+      }
+    });
+  },
+  debug: process.env["SEBA_DEBUG"] === "1",
+});
+
+const session = (await seba.restoreSession()) ?? (await seba.login(webId === undefined ? { issuer } : { issuer, webId }));
+
+console.log(`Signed in as ${session.webId} (provider ${session.provider}).`);
+
+const response = await seba.fetch(session.webId, {
+  headers: { accept: "text/turtle" },
+});
+if (!response.ok) {
+  throw new Error(`Reading the profile failed with HTTP ${String(response.status)}.`);
+}
+console.log(await response.text());
+
+await seba.logout();
+console.log("Signed out.");

package/examples/react/App.tsx

@@ -0,0 +1,127 @@
+/**
+ * React example.
+ *
+ * The same page starts the login, receives the callback and shows the profile. Keep the
+ * component mounted on the redirect URI; `login()` detects the authorization response and
+ * finishes the flow.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import { Seba, isSebaError, type Session } from "@gaballahtech/seba";
+
+const seba = new Seba({
+  clientId: import.meta.env.VITE_SEBA_CLIENT_ID ?? "https://app.example/client-id.jsonld",
+  redirectUri: `${window.location.origin}/auth/callback`,
+});
+
+export default function App() {
+  const [session, setSession] = useState<Session | null>(null);
+  const [profile, setProfile] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    const hasCallback = new URL(window.location.href).searchParams.has("code");
+
+    async function boot(): Promise<void> {
+      try {
+        // On the callback route this completes the pending login; elsewhere it restores.
+        const restored = hasCallback ? await seba.login() : await seba.restoreSession();
+        if (!cancelled) {
+          setSession(restored);
+        }
+      } catch (caught) {
+        if (!cancelled) {
+          setError(describe(caught));
+        }
+      }
+    }
+
+    void boot();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const signIn = useCallback(async (): Promise<void> => {
+    setBusy(true);
+    setError(null);
+    try {
+      // Without a WebID the browser dialog asks for one. The page navigates away, so this
+      // promise normally never resolves.
+      await seba.login();
+    } catch (caught) {
+      setError(describe(caught));
+      setBusy(false);
+    }
+  }, []);
+
+  const loadProfile = useCallback(async (): Promise<void> => {
+    if (session === null) {
+      return;
+    }
+    setBusy(true);
+    setError(null);
+    try {
+      const response = await seba.fetch(session.webId, { headers: { accept: "text/turtle" } });
+      setProfile(response.ok ? await response.text() : `HTTP ${String(response.status)}`);
+    } catch (caught) {
+      setError(describe(caught));
+    } finally {
+      setBusy(false);
+    }
+  }, [session]);
+
+  const signOut = useCallback(async (): Promise<void> => {
+    setBusy(true);
+    try {
+      await seba.logout();
+      setSession(null);
+      setProfile(null);
+    } catch (caught) {
+      setError(describe(caught));
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  return (
+    <main style={{ fontFamily: "system-ui, sans-serif", maxWidth: 720, margin: "3rem auto", padding: "0 1rem" }}>
+      <h1>SEBA + React</h1>
+
+      {session === null ? (
+        <button type="button" onClick={() => void signIn()} disabled={busy}>
+          Sign in with Solid
+        </button>
+      ) : (
+        <section>
+          <p>
+            Signed in as <strong>{session.webId}</strong>
+          </p>
+          <p>Provider: {session.provider}</p>
+          <button type="button" onClick={() => void loadProfile()} disabled={busy}>
+            Read my profile
+          </button>{" "}
+          <button type="button" onClick={() => void signOut()} disabled={busy}>
+            Sign out
+          </button>
+          {profile !== null && <pre style={{ whiteSpace: "pre-wrap", background: "#f1f5f9", padding: 12 }}>{profile}</pre>}
+        </section>
+      )}
+
+      {error !== null && (
+        <p role="alert" style={{ color: "#b91c1c" }}>
+          {error}
+        </p>
+      )}
+    </main>
+  );
+}
+
+function describe(error: unknown): string {
+  if (isSebaError(error)) {
+    return `${error.code}: ${error.message}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}

package/examples/react/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>SEBA React example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/main.tsx"></script>
+  </body>
+</html>

package/examples/react/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+
+const container = document.getElementById("root");
+if (container === null) {
+  throw new Error("The page has no #root element.");
+}
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/examples/react/vite.config.ts

@@ -0,0 +1,27 @@
+/**
+ * Vite config for the React example.
+ *
+ * The `seba` alias points at the TypeScript sources so the example can be built from a
+ * checkout without publishing the package first.
+ */
+
+import { fileURLToPath } from "node:url";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+const root = fileURLToPath(new URL(".", import.meta.url));
+const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
+
+export default defineConfig({
+  root,
+  plugins: [react()],
+  resolve: {
+    alias: {
+      seba: `${packageRoot}src/index.ts`,
+    },
+  },
+  build: {
+    outDir: "dist",
+    emptyOutDir: true,
+  },
+});

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@gaballahtech/seba",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Developer-friendly Solid-OIDC authentication: login, session restoration and DPoP-signed fetch in four methods.",
+  "license": "MIT",
+  "author": "gaballahtech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gaballahtech/seba.git"
+  },
+  "homepage": "https://github.com/gaballahtech/seba#readme",
+  "bugs": {
+    "url": "https://github.com/gaballahtech/seba/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "BUILD_REPORT.md",
+    "VALIDATION_REPORT.md",
+    "LICENSE",
+    "RESEARCH.md",
+    "ARCHITECTURE.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "solid",
+    "solid-oidc",
+    "oidc",
+    "oauth2",
+    "dpop",
+    "pkce",
+    "webid",
+    "authentication"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.examples.json",
+    "typecheck:examples": "tsc -p tsconfig.examples.json",
+    "example:react:build": "vite build --config examples/react/vite.config.ts",
+    "validate:discovery": "npm run build && node scripts/validation/public-discovery.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "idb": "^8.0.3",
+    "jose": "^6.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.2.1",
+    "fake-indexeddb": "^6.2.2",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.6",
+    "vitest": "^5.1.0"
+  }
+}