@elvix.is/sdk 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,34 @@
+MIT License
+
+Copyright (c) 2026 edvone
+Aachen, Germany · edvone.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+────────────────────────────────────────────────────────────────────────
+
+TRADEMARK NOTICE
+
+The MIT License above covers source code only. "elvix", the elvix logomark,
+and the elvix brand chord (deep purple #5d4dff and #8e7dff) are trademarks
+of edvone. Forks may not use the elvix name or logomark to identify
+themselves or their products. Reasonable nominative use ("works with elvix",
+"elvix-compatible", "integrates with elvix") is permitted.
+
+Trademark questions: edvard@edvone.dev

package/README.md

@@ -1,5 +1,191 @@
-# @elvix/sdk
+<p align="center">
+  <img src="https://elvix.is/brand/elvix-icon-512.png" width="96" height="96" alt="elvix" />
+</p>
 
-Placeholder. The real elvix SDK lands here when the public release is ready.
+<h1 align="center">@elvix.is/sdk</h1>
 
-In the meantime: https://elvix.is/docs
+<p align="center">
+  <strong>Identity, kept in Europe.</strong><br/>
+  Passwordless authentication for React + Next.js. Hosted in Aachen, German legal frame.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@elvix.is/sdk"><img src="https://img.shields.io/npm/v/@elvix.is/sdk.svg?color=5d4dff" alt="npm" /></a>
+  <a href="https://www.npmjs.com/package/@elvix.is/sdk"><img src="https://img.shields.io/npm/dm/@elvix.is/sdk.svg?color=8e7dff" alt="downloads" /></a>
+  <a href="https://github.com/021is/elvix-sdk/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/021is/elvix-sdk/ci.yml?branch=main&label=CI" alt="CI" /></a>
+  <a href="https://github.com/021is/elvix-sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-black.svg" alt="MIT" /></a>
+  <a href="https://elvix.is/docs"><img src="https://img.shields.io/badge/docs-elvix.is-5d4dff.svg" alt="docs" /></a>
+  <a href="https://bundlephobia.com/package/@elvix.is/sdk"><img src="https://img.shields.io/bundlephobia/minzip/@elvix.is/sdk?label=min%2Bgzip&color=black" alt="bundle size" /></a>
+</p>
+
+---
+
+## Why elvix
+
+Auth is the highest-leverage place to get an integration right or wrong. Roll your own and you ship an insecure copy of OAuth that future-you debugs at 2am. Use a US provider and your German users live under American legal frame. elvix is opinionated so the first answer is the safe answer, and EU-resident so the legal frame matches your customers.
+
+- Passwordless from day one. Email OTP, passkeys, Google.
+- Drop-in React components. One provider, one form, zero boilerplate.
+- Server-side verify in three lines.
+- Console-configured. Brand colors, allowed methods, redirects all live in elvix Console. The SDK reads them at runtime. No prop drilling.
+- Agent-friendly. Ships an MCP server so Claude, Cursor, Codex, and Gemini can integrate elvix without human shepherding.
+
+## Install
+
+```bash
+bun add @elvix.is/sdk
+# or
+npm install @elvix.is/sdk
+```
+
+## Quickstart
+
+```tsx
+// app/layout.tsx
+import { ElvixProvider } from "@elvix.is/sdk/react";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <ElvixProvider clientId={process.env.NEXT_PUBLIC_ELVIX_CLIENT_ID!}>
+          {children}
+        </ElvixProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx
+// app/sign-in/page.tsx
+"use client";
+
+import { ElvixSignIn } from "@elvix.is/sdk/react";
+import { useRouter } from "next/navigation";
+
+export default function SignInPage() {
+  const router = useRouter();
+  return (
+    <ElvixSignIn
+      onResult={(r) => {
+        if (r.ok) router.push(r.redirect ?? "/dashboard");
+        else console.warn(r.error, r.message);
+      }}
+    />
+  );
+}
+```
+
+```ts
+// app/api/protected/route.ts
+export async function GET(request: Request) {
+  const token = request.headers.get("authorization")?.replace(/^Bearer /, "");
+  if (!token) return new Response("Unauthorized", { status: 401 });
+
+  const res = await fetch("https://elvix.is/api/v1/verify", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${process.env.ELVIX_API_KEY!}`,
+    },
+    body: JSON.stringify({ token }),
+  });
+  const { ok, user, roles } = await res.json();
+  if (!ok) return new Response("Unauthorized", { status: 401 });
+  return Response.json({ hello: user.id, roles });
+}
+```
+
+That is the entire integration.
+
+## AI coding agents
+
+elvix ships first-class agent support. Three surfaces:
+
+1. **Discovery via [llmstxt.org](https://llmstxt.org)**
+
+   ```
+   https://elvix.is/llms.txt          index
+   https://elvix.is/llms-full.txt     flat dump of every doc page
+   https://elvix.is/docs/install.md   per-page Markdown twin
+   https://elvix.is/agent-prompt.md   ready-to-paste system prompt
+   ```
+
+2. **OpenAPI for typed REST access**
+
+   ```
+   https://elvix.is/openapi.yaml          full spec
+   https://elvix.is/openapi.roles.json    per-endpoint role + admin scope
+   ```
+
+3. **MCP server bundled with the SDK**
+
+   ```json
+   {
+     "mcpServers": {
+       "elvix": {
+         "command": "bunx",
+         "args": ["@elvix.is/sdk", "elvix-mcp"],
+         "env": { "ELVIX_API_KEY": "eak_..." }
+       }
+     }
+   }
+   ```
+
+   Read-only by default. `--admin` opts in to mutation tools. Never logs the bearer token.
+
+Full agent guide: <https://elvix.is/docs/agents>
+
+## Components
+
+Every `<Elvix*>` component the SDK ships. Drop-in React, brand chord from `<ElvixProvider>`, no prop drilling.
+
+- Primitives: `ElvixCard`, `ElvixProvider`
+- Sign-in: `ElvixSignIn`, `ElvixSignInButton`, `ElvixRecoverGate`
+- Identity: `ElvixUsername`, `ElvixIdentityForm`, `ElvixAvatar`, `ElvixBanner`, `ElvixRegion`, `ElvixLanguages`
+- Account: `ElvixAddressBook`, `ElvixLegalEntities`, `ElvixSessions`, `ElvixExport`, `ElvixDeactivate`, `ElvixLeave`
+
+Full catalog with previews: <https://elvix.is/docs/components>
+
+## Server helpers
+
+```ts
+import { verifyElvixToken } from "@elvix.is/sdk/server";
+
+const result = await verifyElvixToken(token, { apiKey: process.env.ELVIX_API_KEY! });
+if (result.ok) {
+  // result.user, result.roles, result.scopes, result.memberships
+}
+```
+
+## Brand
+
+Deep purple chord: `#5d4dff` (light) and `#8e7dff` (dark). Override per-app from the Console. Set explicit `brand` on `<ElvixProvider>` to win over the Console default.
+
+## Security
+
+- All requests over TLS 1.3.
+- Session cookies `Secure; HttpOnly; SameSite=Lax`.
+- Per-app session TTL + sliding-window renewal, owner-configurable.
+- API keys carry per-key rate limits (60/min, 10000/day default).
+- CSP, CORS, CSRF double-submit, allowedOrigins enforcement all live on `elvix.is`.
+- Disclosure: <security@elvix.is>.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## Security
+
+Found something? Read [SECURITY.md](./SECURITY.md). Reports go to **security@elvix.is**. Critical issues get a 4-hour response.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). PRs welcome — we run CI on every push and require it green before merge.
+
+## Maintained by
+
+**[edvone](https://edvone.dev)** · Aachen, Germany · [hi@edvone.dev](mailto:hi@edvone.dev)
+
+elvix is an edvone product.

package/dist/chunk-22IQNPXM.js

@@ -0,0 +1,77 @@
+// src/mcp/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var DEFAULT_BASE_URL = "https://elvix.is";
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+function toolName(method, path) {
+  return `${method.toLowerCase()}_${path.replace(/^\/api\//, "").replace(/[\/{}]+/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "")}`;
+}
+async function createElvixMcpServer(opts) {
+  const baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+  const readonly = opts.readonly ?? true;
+  const manifestRes = await fetch(`${baseUrl}/openapi.roles.json`);
+  const manifest = await manifestRes.json();
+  const tools = manifest.endpoints.filter((e) => e.role === "api").filter((e) => readonly ? SAFE_METHODS.has(e.method.toUpperCase()) : true).map((e) => ({
+    name: toolName(e.method, e.path),
+    description: `${e.summary ?? `${e.method} ${e.path}`}${e.adminScope ? " (requires admin scope)" : ""}`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Final URL path (substitute {params})." },
+        body: { type: "object", description: "JSON request body, when applicable." },
+        query: { type: "object", description: "Query parameters." }
+      },
+      required: ["path"]
+    },
+    _meta: { method: e.method, path: e.path, adminScope: e.adminScope ?? false }
+  }));
+  const server = new Server(
+    { name: "elvix", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = tools.find((t) => t.name === req.params.name);
+    if (!tool) {
+      return { content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }], isError: true };
+    }
+    const args = req.params.arguments ?? {};
+    const url = new URL(args.path ?? tool._meta.path, baseUrl);
+    if (args.query) {
+      for (const [k, v] of Object.entries(args.query)) url.searchParams.set(k, v);
+    }
+    const init = {
+      method: tool._meta.method,
+      headers: {
+        authorization: `Bearer ${opts.apiKey}`,
+        "content-type": "application/json"
+      }
+    };
+    if (args.body && !SAFE_METHODS.has(tool._meta.method.toUpperCase())) {
+      init.body = JSON.stringify(args.body);
+    }
+    const res = await fetch(url, init);
+    const text = await res.text();
+    return {
+      content: [{ type: "text", text }],
+      isError: !res.ok
+    };
+  });
+  return {
+    server,
+    connectStdio: async () => {
+      const transport = new StdioServerTransport();
+      await server.connect(transport);
+    }
+  };
+}
+
+export {
+  createElvixMcpServer
+};

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Wire-level types shared between the React, server, and MCP layers.
+ * Mirrors the elvix.is REST envelopes — bump together with the
+ * server when they evolve.
+ */
+type ElvixUser = {
+    id: string;
+    email: string;
+    name?: string;
+    avatarUrl?: string;
+};
+type ElvixVerifyOk = {
+    ok: true;
+    user: ElvixUser;
+    roles: string[];
+    scopes: string[];
+    memberships: string[];
+};
+type ElvixVerifyErr = {
+    ok: false;
+    error: "invalid_token" | "expired" | "revoked" | "membership_blocked" | "rate_limited";
+    message?: string;
+};
+type ElvixVerifyResult = ElvixVerifyOk | ElvixVerifyErr;
+/**
+ * Discriminated union returned to host apps by every `<Elvix*>`
+ * mutation component's `onResult` callback. Always carries "safe to
+ * give back" data — no PII beyond what the customer already sees.
+ */
+type ElvixActionResult<T = unknown> = {
+    ok: true;
+    data?: T;
+    redirect?: string;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+
+export type { ElvixActionResult, ElvixUser, ElvixVerifyErr, ElvixVerifyOk, ElvixVerifyResult };

package/dist/mcp/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/mcp/bin.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import {
+  createElvixMcpServer
+} from "../chunk-22IQNPXM.js";
+
+// src/mcp/bin.ts
+async function main() {
+  const apiKey = process.env.ELVIX_API_KEY;
+  if (!apiKey) {
+    process.stderr.write("ELVIX_API_KEY environment variable is required.\n");
+    process.exit(1);
+  }
+  const args = process.argv.slice(2);
+  const admin = args.includes("--admin");
+  const baseUrl = args.find((a) => a.startsWith("--base-url="))?.split("=")[1];
+  const { connectStdio } = await createElvixMcpServer({
+    apiKey,
+    readonly: !admin,
+    baseUrl
+  });
+  await connectStdio();
+}
+main().catch((e) => {
+  process.stderr.write(`elvix-mcp: ${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(1);
+});

package/dist/mcp/index.d.ts

@@ -0,0 +1,29 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+/**
+ * Programmatic entry to the elvix MCP server. The CLI in `bin.ts`
+ * thin-wraps this so embedders can run an MCP server in-process if
+ * they want (testing, custom transports, multi-server hosts).
+ */
+
+type ElvixMcpOptions = {
+    /** Bearer token used for every tool call. Required. */
+    apiKey: string;
+    /** Override the elvix origin (testing, proxy). */
+    baseUrl?: string;
+    /** When false, mutation tools (POST/PATCH/PUT/DELETE) are hidden
+     *  from the tool list. Default true. Pass `--readonly`/`--admin`
+     *  on the CLI to flip. */
+    readonly?: boolean;
+};
+/**
+ * Build (but don't connect) the MCP server. Returns the Server
+ * instance + a `connect()` to wire stdio. Lets callers choose
+ * transport.
+ */
+declare function createElvixMcpServer(opts: ElvixMcpOptions): Promise<{
+    server: Server;
+    connectStdio: () => Promise<void>;
+}>;
+
+export { type ElvixMcpOptions, createElvixMcpServer };

package/dist/mcp/index.js

@@ -0,0 +1,6 @@
+import {
+  createElvixMcpServer
+} from "../chunk-22IQNPXM.js";
+export {
+  createElvixMcpServer
+};

package/dist/react.d.ts

@@ -0,0 +1 @@
+export { ElvixActionResult, ElvixUser, ElvixVerifyErr, ElvixVerifyOk, ElvixVerifyResult } from './index.js';

package/dist/server.d.ts

@@ -0,0 +1,27 @@
+import { ElvixVerifyResult } from './index.js';
+
+/**
+ * Server-side helpers for verifying elvix-issued session tokens.
+ * Customer backends call `verifyElvixToken` with the request's
+ * Authorization header. Bearer-token auth, no cookies.
+ */
+
+type VerifyOptions = {
+    /** Application API key (Console → Credentials). */
+    apiKey: string;
+    /** Override the elvix origin for testing / proxy setups. */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Default 5000. */
+    timeoutMs?: number;
+};
+/**
+ * Exchange an end-user session token for the verified user envelope
+ * (roles + scopes + memberships). Hit the `/api/v1/verify` endpoint
+ * with the customer's Application API key.
+ *
+ * Returns a discriminated union — never throws on auth failure.
+ * Throws only on infra failure (network, timeout, malformed JSON).
+ */
+declare function verifyElvixToken(token: string, opts: VerifyOptions): Promise<ElvixVerifyResult>;
+
+export { type VerifyOptions, verifyElvixToken };

package/dist/server.js

@@ -0,0 +1,47 @@
+// src/server.ts
+var DEFAULT_BASE_URL = "https://elvix.is";
+async function verifyElvixToken(token, opts) {
+  const url = `${opts.baseUrl ?? DEFAULT_BASE_URL}/api/v1/verify`;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 5e3);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${opts.apiKey}`
+      },
+      body: JSON.stringify({ token }),
+      signal: ctrl.signal
+    });
+    const body = await res.json();
+    if (!res.ok || !body.success || !body.data) {
+      return {
+        ok: false,
+        error: pickError(body.errorMessage, res.status),
+        message: body.errorMessage
+      };
+    }
+    return {
+      ok: true,
+      user: body.data.user,
+      roles: body.data.roles,
+      scopes: body.data.scopes,
+      memberships: body.data.memberships
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function pickError(raw, status) {
+  if (raw === "expired" || raw === "revoked" || raw === "membership_blocked" || raw === "rate_limited") {
+    return raw;
+  }
+  if (status === 401) return "invalid_token";
+  if (status === 403) return "membership_blocked";
+  if (status === 429) return "rate_limited";
+  return "invalid_token";
+}
+export {
+  verifyElvixToken
+};

package/package.json

@@ -1,9 +1,79 @@
 {
   "name": "@elvix.is/sdk",
-  "version": "0.0.0",
-  "description": "elvix — Identity, kept in Europe. SDK (placeholder; real release coming).",
+  "version": "0.1.1",
+  "description": "Official elvix SDK. Drop-in React components, server helpers, and an MCP server so AI coding agents integrate elvix on the first try.",
   "license": "MIT",
   "homepage": "https://elvix.is",
-  "repository": "github:elvix-is/sdk",
-  "keywords": ["auth", "identity", "gdpr", "passkeys", "oauth", "eu"]
+  "author": "edvone <hi@edvone.dev> (https://edvone.dev)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/021is/elvix-sdk.git"
+  },
+  "bugs": "https://github.com/021is/elvix-sdk/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "elvix-mcp": "./dist/mcp/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup src/index.ts src/react.ts src/server.ts src/types.ts src/mcp/index.ts src/mcp/bin.ts --format esm --dts --clean --external react --external next",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "next": ">=15"
+  },
+  "peerDependenciesMeta": {
+    "next": { "optional": true }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "elvix",
+    "authentication",
+    "auth",
+    "passkey",
+    "otp",
+    "google-oauth",
+    "react",
+    "nextjs",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents"
+  ]
 }