provider mode

Author: vanderbr

README.md

@@ -11,22 +11,23 @@ TypeScript server SDK for age verification, designed to help websites implement
 - enforce gate policy server-side
 - verify AgeCheck credentials (`did:web:agecheck.me` and optional demo issuer)
 - issue and validate signed HttpOnly verification cookies
-- keep provider integration pluggable behind one assertion boundary
+- support Existing Gate Integration and multi-provider coexistence
 
 ## Install
 
 ```bash
 pnpm add @agecheck/node
 ```
 
-## Minimal integration path (existing sites)
+## Supported integration modes
 
-This is the shortest production path for hostmasters.
+1. Managed gate mode: use AgeCheck gate route + verify route + signed cookie.
+2. Existing Gate Integration: keep your existing gate and add AgeCheck as one provider option.
+3. Hybrid mode: use AgeCheck gate while also supporting other providers in Provider Mode.
 
-1. Build one SDK instance at server startup.
-2. Protect routes with `requireVerifiedOrRedirect(...)`.
-3. Handle `POST /verify` by verifying JWT + session and setting signed cookie.
-4. Trust cookie validation on every protected request.
+All modes converge into one normalized provider assertion and one signed cookie pipeline.
+
+## Minimal managed-gate integration
 
 ```ts
 import { AgeCheckSdk } from "@agecheck/node";
@@ -44,7 +45,7 @@ const sdk = new AgeCheckSdk({
   cookie: {
     secret: process.env.AGECHECK_COOKIE_SECRET!,
     cookieName: "agecheck_verified",
-    ttlSeconds: 86400,
+    ttlSeconds: 86400, // hostmaster-controlled (e.g. 31536000 for 1 year)
   },
 });
 
@@ -85,6 +86,63 @@ export async function verifyEndpoint(request: Request): Promise<Response> {
 }
 ```
 
+## Existing Gate Integration (Provider Mode)
+
+Use these helpers when a hostmaster already has a gate flow and wants to add AgeCheck as a provider:
+
+```ts
+import {
+  AgeCheckSdk,
+  buildSetCookieFromProviderAssertion,
+  normalizeExternalProviderAssertion,
+  verifyAgeCheckCredential,
+  type ProviderVerificationResult,
+} from "@agecheck/node";
+
+const sdk = new AgeCheckSdk({
+  deploymentMode: "production",
+  verify: { requiredAge: 18 },
+  cookie: { secret: process.env.AGECHECK_COOKIE_SECRET! },
+});
+
+export async function verifyProviderEndpoint(body: {
+  provider?: string;
+  jwt?: string;
+  payload?: { agegateway_session?: string };
+  redirect?: string;
+}): Promise<Response> {
+  const expectedSession = body.payload?.agegateway_session;
+  if (typeof expectedSession !== "string" || expectedSession.length === 0) {
+    return Response.json({ verified: false, code: "invalid_input", error: "Missing session." }, { status: 400 });
+  }
+
+  let assertion: ProviderVerificationResult;
+  if ((body.provider ?? "agecheck") === "agecheck") {
+    assertion = await verifyAgeCheckCredential(sdk, {
+      jwt: body.jwt ?? "",
+      expectedSession,
+      assurance: "passkey",
+    });
+  } else {
+    const externalResult: ProviderVerificationResult = await verifyOtherProvider(body);
+    assertion = normalizeExternalProviderAssertion(externalResult, expectedSession);
+  }
+
+  if (!assertion.verified) {
+    return Response.json(
+      { verified: false, code: assertion.code, error: assertion.message, detail: assertion.detail },
+      { status: 401 },
+    );
+  }
+
+  const setCookie = await buildSetCookieFromProviderAssertion(sdk, assertion);
+  return new Response(JSON.stringify({ verified: true, redirect: body.redirect ?? "/" }), {
+    status: 200,
+    headers: { "content-type": "application/json", "set-cookie": setCookie },
+  });
+}
+```
+
 ## Deployment modes
 
 - `production`
@@ -94,19 +152,28 @@ export async function verifyEndpoint(request: Request): Promise<Response> {
   - accepts demo + production issuer credentials
   - gate is always raised
 
-## Provider boundary
+## Provider assertion contract
 
-AgeCheck is the default provider, but you can normalize other provider results into the same assertion model and keep one cookie pipeline.
+Provider results normalize to this shape:
 
 ```ts
-const cookie = await sdk.buildSetCookieFromAssertion({
-  provider: "my-provider",
-  verified: true,
-  level: "21+",
-  verifiedAtUnix: Math.floor(Date.now() / 1000),
-});
+{
+  provider: string;
+  verified: true;
+  level: "18+" | "21+" | `${number}+`;
+  session: string; // UUID
+  verifiedAtUnix: number;
+  assurance?: string;
+  verificationType?: "passkey" | "oid4vp" | "other";
+  evidenceType?: "webauthn_assertion" | "sd_jwt" | "zk_attestation" | "other";
+  providerTransactionId?: string;
+  loa?: string;
+}
 ```
 
+This keeps provider internals isolated while preserving one site-level cookie and enforcement model.
+`payload.agegateway_session` and provider assertion `session` are treated as required UUID values.
+
 ## Framework adapters
 
 `@agecheck/node` includes framework adapter helpers:

docs/ADAPTERS.md

@@ -33,6 +33,21 @@ All adapters support the same provider boundary:
 
 Provider verifier output is normalized into a single signed-cookie issuance path, so enforcement logic remains identical across providers.
 
+Provider verifier success shape:
+
+```ts
+{
+  verified: true;
+  provider: string;
+  level: `${number}+`;
+  session: string; // UUID
+  verifiedAtUnix?: number;
+  assurance?: string;
+}
+```
+
+`session` is required and must be a UUID. `payload.agegateway_session` is required and must match the provider `session`.
+
 ## End-to-end deployment docs
 
 - Hostmaster flow: `/docs/HOSTMASTER_E2E.md`

docs/EXISTING_SITES.md

@@ -9,6 +9,16 @@ This guide describes how to add AgeCheck to an existing adult website without re
 3. Redirect unverified users to your gate route (for example `/ageverify`).
 4. Verify JWT at `POST /verify`, set signed HttpOnly cookie, redirect back.
 
+## Existing Gate Integration (Provider Mode)
+
+If your site already has a gate and multiple providers, add AgeCheck as one provider option:
+
+1. Keep your gate UI and policy engine unchanged.
+2. Generate or forward the provider session identifier (AgeCheck expects `agegateway_session`).
+3. For AgeCheck, call `verifyAgeCheckCredential(...)`.
+4. For other providers, map result with `normalizeExternalProviderAssertion(...)`.
+5. Issue one canonical cookie with `buildSetCookieFromProviderAssertion(...)`.
+
 ## Why this pattern
 
 - enforcement remains server-side
@@ -33,7 +43,18 @@ Set with:
 
 ## Provider coexistence
 
-If you support more than one verifier, normalize each verification result into the SDK `VerificationAssertion` shape and reuse the same signed-cookie issuance and enforcement logic.
+If you support more than one verifier, normalize each verification result into the provider assertion shape and reuse the same signed-cookie issuance and enforcement logic:
+
+```ts
+{
+  provider: string;
+  verified: true;
+  level: `${number}+`;
+  session: string;
+  verifiedAtUnix: number;
+  assurance?: string;
+}
+```
 
 ## Framework adapters
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agecheck/node",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "AgeCheck Node SDK for gate policy, JWT verification, and signed verification cookies.",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@agecheck/core": "^0.1.0"
+    "@agecheck/core": "^0.2.0"
   },
   "devDependencies": {
     "@agecheck/core": "^0.1.1",

pnpm-lock.yaml

@@ -1,4 +1,5 @@
 packages:
+  - "."
   - "worker-demo"
 
 onlyBuiltDependencies:

pnpm-workspace.yaml

@@ -11,7 +11,18 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { AgeCheckError, ErrorCode, type AgeCheckSdk, type VerificationAssertion } from "@agecheck/core";
+import {
+  AgeCheckError,
+  ErrorCode,
+  type AgeCheckSdk,
+} from "@agecheck/core";
+import {
+  buildSetCookieFromProviderAssertion,
+  normalizeExternalProviderAssertion,
+  type NormalizedProviderVerificationResult,
+  type ProviderVerificationResult,
+  verifyAgeCheckCredential,
+} from "../provider-mode.js";
 
 export interface AdapterVerifyBody {
   provider?: string;
@@ -22,24 +33,6 @@ export interface AdapterVerifyBody {
   redirect?: string;
 }
 
-export interface ProviderVerificationSuccess {
-  verified: true;
-  provider: string;
-  level: string;
-  session: string;
-  verifiedAtUnix?: number;
-  assurance?: string;
-}
-
-export interface ProviderVerificationFailure {
-  verified: false;
-  code: string;
-  message: string;
-  detail?: string;
-}
-
-export type ProviderVerificationResult = ProviderVerificationSuccess | ProviderVerificationFailure;
-
 export type ProviderVerifier = (body: AdapterVerifyBody) => Promise<ProviderVerificationResult>;
 
 export interface AdapterOptions {
@@ -210,56 +203,37 @@ export async function verifyAndBuildOutcome(
   }
 
   const expectedSession = body.payload?.agegateway_session;
+  if (typeof expectedSession !== "string" || expectedSession.length === 0) {
+    return failure(400, ErrorCode.INVALID_INPUT, "Missing payload.agegateway_session.");
+  }
   const redirect = normalizeRedirect(body.redirect);
   const provider = body.provider ?? "agecheck";
 
-  let assertion: VerificationAssertion;
+  let assertion: NormalizedProviderVerificationResult;
   if (provider === "agecheck") {
-    if (typeof body.jwt !== "string") {
-      return failure(400, ErrorCode.INVALID_INPUT, "Missing jwt for agecheck provider");
-    }
-
-    const verify = await sdk.verifyToken(body.jwt, expectedSession);
-    if (!verify.ok) {
-      return failure(401, verify.code, "Age validation failed.", verify.detail);
-    }
-
-    assertion = {
+    const ageCheckResult = await verifyAgeCheckCredential(sdk, {
+      jwt: body.jwt ?? "",
+      expectedSession,
       provider: "agecheck",
-      verified: true,
-      level: verify.ageTier,
-      verifiedAtUnix: Math.floor(Date.now() / 1000),
       assurance: "passkey",
-    };
+    });
+    assertion = ageCheckResult;
   } else {
     if (typeof options.providerVerifier !== "function") {
       return failure(400, ErrorCode.INVALID_INPUT, "Unknown provider and no provider verifier configured");
     }
 
     const providerResult = await options.providerVerifier(body);
-    if (!providerResult.verified) {
-      return failure(401, providerResult.code, providerResult.message, providerResult.detail);
-    }
-
-    if (expectedSession !== undefined && providerResult.session !== expectedSession) {
-      return failure(401, ErrorCode.SESSION_BINDING_MISMATCH, "Session binding mismatch.");
-    }
+    assertion = normalizeExternalProviderAssertion(providerResult, expectedSession);
+  }
 
-    const providerAssertion: VerificationAssertion = {
-      provider: providerResult.provider,
-      verified: true,
-      level: providerResult.level,
-      verifiedAtUnix: providerResult.verifiedAtUnix ?? Math.floor(Date.now() / 1000),
-    };
-    if (providerResult.assurance !== undefined) {
-      providerAssertion.assurance = providerResult.assurance;
-    }
-    assertion = providerAssertion;
+  if (!assertion.verified) {
+    return failure(401, assertion.code, assertion.message, assertion.detail);
   }
 
   let setCookie: string;
   try {
-    setCookie = await sdk.buildSetCookieFromAssertion(assertion);
+    setCookie = await buildSetCookieFromProviderAssertion(sdk, assertion);
   } catch (error: unknown) {
     if (error instanceof AgeCheckError) {
       return failure(500, error.code, "Failed to issue verification cookie", error.message);