@eudi-verify/server 0.1.0

package/LICENSE

@@ -0,0 +1,184 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of recording and
+      tracking Contributions to the Work, but excluding communication that is
+      conspicuously marked or designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any such
+      Contribution as incorporated in the Work constitutes direct or
+      contributory patent infringement, then any patent licenses granted to
+      You under this License for that Work shall terminate as of the date
+      such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, either on its own or as part of the Work.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
+      PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may offer such obligations only on
+      Your own behalf and on Your sole responsibility, not on behalf of
+      any other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by, or
+      claims asserted against, such Contributor by reason of your accepting
+      any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024 EUDI Wallet Verifier Kit Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,258 @@
+# @eudi-verify/server
+
+Framework-agnostic EUDI Wallet verifier API handlers.
+
+## Installation
+
+```bash
+pnpm add @eudi-verify/server
+```
+
+## Quick Start
+
+```ts
+import {
+  createVerifierHandlers,
+  OpenEudiEngine,
+  MemoryKVStore,
+} from '@eudi-verify/server';
+
+// 1. Create engine and store
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000/api/eudi';
+const engine = new OpenEudiEngine({ mode: 'demo', baseUrl: BASE_URL });
+const store = new MemoryKVStore();
+
+// 2. Create handlers
+const handlers = createVerifierHandlers({
+  engine,
+  store,
+  baseUrl: BASE_URL,
+  mode: 'demo',
+  tokenSecret: process.env.TOKEN_SECRET!, // 32+ chars
+});
+
+// 3. Mount on your framework
+// See framework examples below
+```
+
+## Framework Integration
+
+### Node.js HTTP
+
+```ts
+import http from 'node:http';
+
+function buildContext(req, params = {}, body = undefined) {
+  return {
+    ip: req.socket.remoteAddress ?? '127.0.0.1',
+    origin: req.headers.origin,
+    params,
+    body,
+  };
+}
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url!, `http://${req.headers.host}`);
+  
+  // Route to handlers
+  if (url.pathname === '/sessions' && req.method === 'POST') {
+    const body = await readBody(req);
+    const result = await handlers.createSession(buildContext(req, {}, JSON.parse(body)));
+    sendJson(res, result.status, result.body, result.headers);
+  }
+  // ... other routes
+});
+```
+
+### Express
+
+```ts
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+function buildContext(req, params = {}, body = undefined) {
+  return {
+    ip: req.ip ?? '127.0.0.1',
+    origin: req.headers.origin,
+    params,
+    body,
+  };
+}
+
+app.post('/sessions', async (req, res) => {
+  const result = await handlers.createSession(buildContext(req, {}, req.body));
+  res.status(result.status).set(result.headers).json(result.body);
+});
+
+app.get('/sessions/:id', async (req, res) => {
+  const result = await handlers.getSession(buildContext(req, { sessionId: req.params.id }));
+  res.status(result.status).set(result.headers).json(result.body);
+});
+
+app.post('/sessions/:id/cancel', async (req, res) => {
+  const result = await handlers.cancelSession(buildContext(req, { sessionId: req.params.id }));
+  res.status(result.status).set(result.headers).json(result.body);
+});
+
+app.post('/tokens/verify', async (req, res) => {
+  const result = await handlers.verifyToken(buildContext(req, {}, req.body));
+  res.status(result.status).json(result.body);
+});
+```
+
+### Hono
+
+```ts
+import { Hono } from 'hono';
+
+const app = new Hono();
+
+function buildContext(c, params = {}, body = undefined) {
+  return {
+    ip: c.req.header('x-forwarded-for') ?? '127.0.0.1',
+    origin: c.req.header('origin'),
+    params,
+    body,
+  };
+}
+
+app.post('/sessions', async (c) => {
+  const result = await handlers.createSession(buildContext(c, {}, await c.req.json()));
+  return c.json(result.body, result.status, result.headers);
+});
+
+// ... other routes
+```
+
+## Configuration
+
+```ts
+interface VerifierConfig {
+  engine: VerifierEngine;     // OpenEudiEngine or MockEngine
+  store: IKVStore;            // MemoryKVStore (or Redis for production)
+  baseUrl: string;            // Public callback URL (e.g., https://example.com/api/eudi)
+  mode: 'demo' | 'production';
+  tokenSecret: string;        // HMAC secret, 32+ characters
+  tokenTtlMs?: number;        // Default: 300000 (5 min)
+  sessionTtlMs?: number;      // Default: 300000 (5 min)
+  rateLimit?: {
+    maxRequests: number;      // Default: 10
+    windowMs: number;         // Default: 60000 (1 min)
+  };
+  allowedOrigins?: string[];  // CORS/Origin check (empty = allow all)
+}
+```
+
+## Handlers
+
+| Handler | Route | Description |
+|---------|-------|-------------|
+| `createSession(body, ctx)` | `POST /sessions` | Create verification session |
+| `getSession(id)` | `GET /sessions/:id` | Get session status |
+| `cancelSession(id)` | `POST /sessions/:id/cancel` | Cancel active session |
+| `verifyToken(body)` | `POST /tokens/verify` | Validate verification token |
+| `handleCallback(data)` | `POST /callback` | Wallet callback (internal) |
+
+## Error Boundaries
+
+Handlers return `{ status, headers?, body }` — they **never throw**. Your framework route is the integration boundary.
+
+### Three error shapes
+
+**1. HTTP errors** — returned as `{ error, message, details? }` with 4xx/5xx status:
+
+| Status | `error` code | Typical cause |
+|--------|--------------|---------------|
+| 400 | `bad_request` | Invalid input |
+| 403 | `forbidden` | Origin not in `allowedOrigins` |
+| 404 | `not_found` | Session missing |
+| 409 | `conflict` | Cancel on terminal session |
+| 429 | `rate_limited` | Rate limit exceeded |
+| 500 | `internal_error` | Engine failure on create |
+
+**2. Session outcomes** — HTTP 200, check `body.status`:
+
+| `status` | Meaning |
+|----------|---------|
+| `rejected` | User declined in wallet |
+| `expired` | Session TTL elapsed |
+| `error` | VP validation or engine failure |
+
+These surface to your frontend via `GET /sessions/:id` polling, not via callback HTTP status.
+
+**3. Token soft failures** — `verifyToken` returns HTTP 200 with `{ valid: false, error: 'invalid_token' | 'expired' | 'already_consumed' | ... }`.
+
+### Wallet callback (`POST /callback`)
+
+Called by the wallet during OpenID4VP — **not by your application code**.
+
+- **400** — callback could not be processed (missing body, parse error, unknown session).
+- **200** `{ status: 'ok' }` — callback received; verification outcome is stored on the session.
+
+A verification failure (bad VP, crypto error) still returns **200** to the wallet. The session moves to `status: 'error'` or `'rejected'`. Your page discovers this when polling `getSession`.
+
+To report callback-path failures server-side, inspect the session after handling the callback (or rely on frontend polling to surface `error` state).
+
+### Route adapter pattern
+
+```ts
+app.post('/sessions', async (req, res) => {
+  const result = await handlers.createSession(buildContext(req, {}, req.body));
+
+  if (result.status >= 400 && 'error' in result.body) {
+    // Your error reporting hook
+    reportError({ handler: 'createSession', ...result.body });
+  }
+
+  res.status(result.status).set(result.headers).json(result.body);
+});
+```
+
+Internal failures are logged to `console.error` with a `[eudi-verify]` prefix. There is no built-in logger injection — wrap handler calls for structured reporting.
+
+## Token Verification
+
+**Important:** There are two different tokens in the flow:
+
+1. **VP Token** (Verifiable Presentation) — Comes from the EUDI Wallet, verified by the engine using cryptographic signatures and trust lists
+2. **Verification Token** — Minted by your server after VP verification succeeds, HMAC-signed with `TOKEN_SECRET`, returned to client as proof of successful verification
+
+The `tokenSecret` config parameter is for signing the **Verification Token** only.
+
+After the widget emits a `verified` event with a token, validate it server-side:
+
+```ts
+// In your protected endpoint
+app.post('/checkout', async (req, res) => {
+  const { eudiToken } = req.body;
+  
+  const result = await handlers.verifyToken({ token: eudiToken });
+  
+  if (result.body.valid) {
+    // Token is valid, claims are verified
+    const { age_over_18, nationality } = result.body.claims;
+    // Proceed with checkout...
+  } else {
+    // Token invalid, expired, or already used
+    res.status(401).json({ error: result.body.error });
+  }
+});
+```
+
+## Demo Mode Warning
+
+⚠️ Demo mode accepts simulated credentials. **Never use in production.**
+
+Demo mode is indicated by:
+- Console warning on startup
+- `X-Eudi-Mode: demo` header on all responses
+
+## API Reference
+
+See [openapi/eudi-verifier.yaml](../../openapi/eudi-verifier.yaml) for the full OpenAPI 3.1 specification.
+
+## License
+
+Apache-2.0