@human-gateway/sdk 0.0.1 → 0.1.0-alpha.1

package/README.md

@@ -1,21 +1,711 @@
 # Human Gateway SDK
 
-Official Human Gateway SDK placeholder.
+Human Gateway SDK lets partners add privacy-first human verification and human authentication to their apps without handling identity, biometrics, World ID internals, nullifiers, or proof verification logic.
 
-This package reserves the official Human Gateway SDK namespace.
+Human Gateway is designed around two identifiers:
 
-The production SDK is under active development and will be released in a future version.
+```txt
+projectId   -> identifies your Human Gateway project
+actionKey   -> identifies the specific verify/auth flow inside that project
+```
 
-## Status
+For production integrations, pass an `actionKey` explicitly.
 
-Placeholder release (`v0.0.1`)
+---
 
-## Package
+## Installation
 
 ```bash
 npm install @human-gateway/sdk
 ```
 
-## Purpose
+> The SDK is currently in alpha. Package publication should be handled as a controlled release step. For local development, use the package from the Human Gateway monorepo.
+
+---
+
+## Quickstart: Verify a human
+
+```ts
+import { HumanGateway } from "@human-gateway/sdk";
+
+const hg = new HumanGateway({
+  projectId: "project_xxx",
+});
+
+const result = await hg.verify({
+  actionKey: "hg_verify_action_key_xxx",
+});
+
+if (result.verified_human) {
+  // Hide verify button
+  // Show verified badge
+  // Optionally wait for the signed backend callback before persisting state
+}
+```
+
+Example verification result:
+
+```json
+{
+  "success": true,
+  "verified_human": true,
+  "verification_level": "orb",
+  "unique_for_partner": true,
+  "already_verified": false,
+  "project_id": "project_xxx"
+}
+```
+
+---
+
+## Quickstart: Sign in a verified human
+
+```ts
+import { HumanGateway } from "@human-gateway/sdk";
+
+const hg = new HumanGateway({
+  projectId: "project_xxx",
+});
+
+const result = await hg.auth({
+  actionKey: "hg_auth_action_key_xxx",
+});
+
+if (result.success && result.verified_human) {
+  // Update your UI
+  // Store the returned partner-scoped session only according to your own app flow
+}
+```
+
+Example auth result:
+
+```json
+{
+  "success": true,
+  "event": "auth.completed",
+  "verified_human": true,
+  "verification_level": "orb",
+  "partner_user_id": "partner_user_xxx",
+  "auth_session_id": "auth_session_xxx",
+  "project_id": "project_xxx",
+  "expires_at": "2026-06-25T00:00:00.000Z"
+}
+```
+
+---
+
+## Project vs Action
+
+A Human Gateway project represents one partner integration.
+
+An action represents a specific flow inside that project.
+
+Example:
+
+```txt
+Project: My SaaS App
+
+Actions:
+- Verify signup
+- Auth login
+- Verify voting
+- Auth dashboard access
+```
+
+Use the same `projectId` for the project and pass the correct `actionKey` for the flow you want to run.
+
+```ts
+await hg.verify({
+  actionKey: "hg_verify_signup_xxx",
+});
+
+await hg.auth({
+  actionKey: "hg_auth_login_xxx",
+});
+```
+
+If `actionKey` is omitted, Human Gateway may use a fallback active action for compatibility. Explicit `actionKey` usage is recommended for production integrations.
+
+---
+
+## What Human Gateway does
+
+Human Gateway verifies that a real human completed a World ID proof inside a specific project/action context.
+
+Human Gateway does **not** expose:
+
+* personal identity
+* emails
+* names
+* biometrics
+* World ID nullifiers
+* raw World ID proof data
+* internal Human Gateway user records
+
+The partner receives only scoped results needed to update product behavior.
+
+---
+
+## Frontend options
+
+```ts
+const result = await hg.verify({
+  actionKey: "hg_verify_action_key_xxx",
+  onOpen: () => {
+    console.log("Verification popup opened");
+  },
+  onSuccess: (result) => {
+    console.log("Verification completed:", result);
+  },
+  onError: (error) => {
+    console.error("Verification failed:", error.code);
+  },
+});
+```
+
+```ts
+const result = await hg.auth({
+  actionKey: "hg_auth_action_key_xxx",
+  onOpen: () => {
+    console.log("Auth popup opened");
+  },
+  onSuccess: (result) => {
+    console.log("Auth completed:", result);
+  },
+  onError: (error) => {
+    console.error("Auth failed:", error.code);
+  },
+});
+```
+
+---
+
+## SDK configuration
+
+```ts
+const hg = new HumanGateway({
+  projectId: "project_xxx",
+  environment: "production",
+  mode: "auto",
+  timeoutMs: 300000,
+});
+```
+
+Available options:
+
+```ts
+type HumanGatewayOptions = {
+  projectId: string;
+  environment?: "production" | "sandbox";
+  mode?: "auto" | "popup" | "modal" | "redirect";
+  baseUrl?: string;
+  timeoutMs?: number;
+};
+```
+
+`environment` identifies the intended Human Gateway project environment.
+
+```txt
+production -> production project/action configuration
+sandbox    -> sandbox project/action configuration
+```
+
+Both `production` and `sandbox` currently use the hosted Human Gateway domain by default:
+
+```txt
+https://humangateway.dev
+```
+
+For local development, pass `baseUrl` explicitly.
+
+Alpha behavior:
+
+* `popup` is supported.
+* `auto` currently uses popup behavior.
+* `modal` is planned.
+* `redirect` is planned.
+
+---
+
+## Verify options
+
+```ts
+type HumanGatewayVerifyOptions = {
+  actionKey?: string;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onSuccess?: (result: HumanGatewayResult) => void;
+  onError?: (error: HumanGatewayError) => void;
+};
+```
+
+Verify result:
+
+```ts
+type HumanGatewayResult = {
+  success: boolean;
+  verified_human: boolean;
+  verification_level: "device" | "document" | "secure_document" | "orb" | null;
+  unique_for_partner: boolean;
+  already_verified: boolean;
+  project_id: string;
+};
+```
+
+---
+
+## Auth options
+
+```ts
+type HumanGatewayAuthOptions = {
+  actionKey?: string;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onSuccess?: (result: HumanGatewayAuthResult) => void;
+  onError?: (error: HumanGatewayError) => void;
+};
+```
+
+Auth result:
+
+```ts
+type HumanGatewayAuthResult = {
+  success: boolean;
+  event?: "auth.completed";
+  verified_human: boolean;
+  verification_level: "device" | "document" | "secure_document" | "orb" | null;
+  partner_user_id: string;
+  auth_session_id: string;
+  project_id: string;
+  expires_at: string;
+};
+```
+
+---
+
+## Popup behavior
+
+The SDK opens a Human Gateway hosted flow in a centered browser popup.
+
+This is expected behavior:
+
+* The popup may show the browser address bar.
+* The popup may be resizable or maximizable depending on the browser.
+* The popup attempts to close itself after a successful flow.
+* Some browsers may prevent programmatic closing; in that case, the user can close it manually.
+
+The visible address bar is intentional and useful: it lets users confirm they are interacting with a legitimate Human Gateway domain.
+
+### User gesture requirement
+
+Call `hg.verify()` or `hg.auth()` directly from a user action such as a button click.
+
+Modern browsers may block popups if they are opened after a long asynchronous operation, delayed promise, timer, or background task. For the best success rate, start the Human Gateway flow immediately inside the user interaction handler.
+
+Recommended:
+
+```ts
+button.addEventListener("click", async () => {
+  const result = await hg.verify({
+    actionKey: "hg_verify_action_key_xxx",
+  });
+
+  console.log(result);
+});
+```
+
+Avoid delaying the popup:
+
+```ts
+button.addEventListener("click", async () => {
+  await doLongAsyncWork();
+
+  const result = await hg.verify({
+    actionKey: "hg_verify_action_key_xxx",
+  });
+
+  console.log(result);
+});
+```
+
+---
+
+## Allowed origin vs callback URL
+
+Human Gateway uses two different URLs during an integration:
+
+```txt
+Allowed origin -> frontend origin that can launch hosted Human Gateway flows
+Callback URL   -> backend endpoint that receives signed POST callbacks
+```
+
+Examples:
+
+```txt
+Allowed origin: https://yourapp.com
+Callback URL:   https://yourapp.com/api/hg/callback
+```
+
+Do not configure only your domain as the callback URL:
+
+```txt
+Incorrect callback URL: https://yourapp.com
+```
+
+Human Gateway sends `POST` requests to the exact callback URL configured in Partner Console. The callback URL must include the full backend endpoint path. Partners can choose their own backend route, for example:
+
+```txt
+https://yourapp.com/api/hg/callback
+https://yourapp.com/api/webhooks/human-gateway
+https://yourapp.com/webhooks/hg
+https://yourapp.com/api/world/hg
+```
+
+The allowed origin is used by the frontend SDK and hosted flows. The callback URL is used by Human Gateway server-to-server delivery.
+
+---
+
+## Frontend result vs backend callback
+
+The frontend SDK result is useful for immediate UI updates.
+
+The signed backend callback should be treated as the durable source of truth.
+
+```txt
+Frontend result  -> update UI
+Signed callback  -> persist verified/auth state in partner backend
+```
+
+A malicious user can manipulate frontend state. They cannot forge a valid Human Gateway callback without the callback secret.
+
+---
+
+## Backend callback verification
+
+Human Gateway sends signed callbacks to the partner backend.
+
+Configure the callback URL in Partner Console as the full backend endpoint path, for example:
+
+```txt
+https://yourapp.com/api/hg/callback
+```
+
+Do not configure only `https://yourapp.com`; Human Gateway will send the callback to the exact URL you enter.
+
+Server-side helpers are exported from `@human-gateway/sdk/server`.
+
+You do not need to create a `HumanGateway` instance on your backend. The server helpers are pure functions designed to validate callback requests using the raw request body, signed headers, and your project callback secret.
+
+Callback headers:
+
+```txt
+x-hg-event-id
+x-hg-event
+x-hg-project-id
+x-hg-timestamp
+x-hg-signature
+```
+
+Example callback payload:
+
+```json
+{
+  "event_id": "callback_event_xxx",
+  "event": "verification.completed",
+  "success": true,
+  "verified_human": true,
+  "verification_level": "orb",
+  "unique_for_partner": false,
+  "already_verified": true,
+  "project_id": "project_xxx",
+  "created_at": "2026-06-25T00:00:00.000Z"
+}
+```
+
+---
+
+## Recommended callback verification
+
+Use `verifyCallback` when you want Human Gateway to validate the signature, timestamp, required headers, JSON payload, event id, event type, and project id consistency.
+
+```ts
+import { verifyCallback } from "@human-gateway/sdk/server";
+
+export async function POST(request: Request) {
+  const body = await request.text();
+
+  try {
+    const callback = verifyCallback({
+      body,
+      headers: request.headers,
+      // Use the callback secret configured for this project in Partner Console.
+      // You can generate or rotate it from the project callback settings.
+      secret: process.env.HG_CALLBACK_SECRET!,
+      expectedProjectId: "project_xxx",
+    });
+
+    if (callback.event === "verification.completed") {
+      const payload = callback.payload;
+
+      if (payload.verified_human === true) {
+        // Persist verified state in your backend
+      }
+    }
+
+    if (callback.event === "auth.completed") {
+      const payload = callback.payload;
+
+      if (payload.verified_human === true) {
+        // Persist or reconcile auth state in your backend
+      }
+    }
+
+    return Response.json({ success: true });
+  } catch {
+    return new Response("Invalid Human Gateway callback", {
+      status: 401,
+    });
+  }
+}
+```
+
+---
+
+## Low-level signature verification
+
+Use `verifyCallbackSignature` only if you want to verify the signature yourself and handle payload/header validation manually.
+
+```ts
+import { verifyCallbackSignature } from "@human-gateway/sdk/server";
+
+export async function POST(request: Request) {
+  const rawBody = await request.text();
+
+  const isValid = verifyCallbackSignature({
+    rawBody,
+    timestamp: request.headers.get("x-hg-timestamp"),
+    signature: request.headers.get("x-hg-signature"),
+    // Use the callback secret configured for this project in Partner Console.
+    // You can generate or rotate it from the project callback settings.
+    secret: process.env.HG_CALLBACK_SECRET!,
+  });
+
+  if (!isValid) {
+    return new Response("Invalid Human Gateway signature", {
+      status: 401,
+    });
+  }
+
+  const payload = JSON.parse(rawBody);
+
+  return Response.json({
+    success: true,
+    event: payload.event,
+  });
+}
+```
+
+---
+
+## Callback verification errors
+
+```ts
+type HumanGatewayCallbackErrorCode =
+  | "callback_missing_body"
+  | "callback_missing_secret"
+  | "callback_missing_header"
+  | "callback_invalid_timestamp"
+  | "callback_expired_timestamp"
+  | "callback_invalid_signature_format"
+  | "callback_invalid_signature"
+  | "callback_invalid_json"
+  | "callback_invalid_payload"
+  | "callback_event_id_mismatch"
+  | "callback_event_type_mismatch"
+  | "callback_project_id_mismatch";
+```
+
+Example:
+
+```ts
+import {
+  HumanGatewayCallbackError,
+  verifyCallback,
+} from "@human-gateway/sdk/server";
+
+try {
+  const callback = verifyCallback({
+    body,
+    headers,
+    secret: process.env.HG_CALLBACK_SECRET!,
+  });
+} catch (error) {
+  if (error instanceof HumanGatewayCallbackError) {
+    console.error("Invalid Human Gateway callback:", error.code);
+  }
+}
+```
+
+---
+
+## SDK error codes
+
+```ts
+type HumanGatewayErrorCode =
+  | "popup_blocked"
+  | "user_closed"
+  | "timeout"
+  | "invalid_message"
+  | "invalid_origin"
+  | "verification_failed"
+  | "auth_failed"
+  | "unknown_error";
+```
+
+Common handling:
+
+```ts
+import { HumanGateway, HumanGatewayError } from "@human-gateway/sdk";
+
+const hg = new HumanGateway({
+  projectId: "project_xxx",
+});
+
+try {
+  const result = await hg.verify({
+    actionKey: "hg_verify_action_key_xxx",
+  });
+} catch (error) {
+  if (error instanceof HumanGatewayError) {
+    if (error.code === "user_closed") {
+      // User cancelled the flow
+    }
+
+    if (error.code === "popup_blocked") {
+      // Ask the user to allow popups
+    }
+
+    if (error.code === "verification_failed") {
+      // The hosted verification flow did not complete successfully
+    }
+  }
+}
+```
+
+---
+
+## Local development
+
+```ts
+const hg = new HumanGateway({
+  projectId: "project_1a7f21ff5e261645",
+  environment: "sandbox",
+  baseUrl: "http://localhost:3000",
+});
+
+await hg.verify({
+  actionKey: "hg_verify_action_key_xxx",
+});
+
+await hg.auth({
+  actionKey: "hg_auth_action_key_xxx",
+});
+```
+
+`baseUrl` overrides the hosted Human Gateway domain. Use it for local testing, previews, or controlled internal validation.
+
+---
+
+## Privacy-first guarantees
+
+Human Gateway does not identify the user.
+
+It verifies humanity inside a project/action context.
+
+The partner may receive:
+
+```txt
+success
+verified_human
+verification_level
+unique_for_partner
+already_verified
+partner_user_id
+auth_session_id
+project_id
+expires_at
+```
+`verification_level` can be `device`, `document`, `secure_document`, `orb`, or `null`.
+
+Human Gateway only returns the value provided by World ID. It does not infer, upgrade, or claim a stronger verification level.
+
+The partner does not receive:
+
+```txt
+World ID nullifier
+biometric data
+personal identity
+World proof internals
+Human Gateway internal user object
+raw World ID proof data
+```
+
+---
+
+## Recommended partner verification flow
+
+```txt
+1. User clicks "Verify with Human Gateway"
+2. SDK opens Human Gateway popup
+3. User completes World ID proof
+4. Partner frontend receives UX result
+5. Human Gateway sends signed callback to partner backend
+6. Partner backend verifies callback
+7. Partner persists verified status
+8. Partner hides verification button
+```
+
+---
+
+## Recommended partner auth flow
+
+```txt
+1. User clicks "Sign in with Human Gateway"
+2. SDK opens Human Gateway Auth popup
+3. User completes World ID proof
+4. Human Gateway creates a partner-scoped auth session
+5. Partner frontend receives UX result
+6. Human Gateway sends signed callback to partner backend
+7. Partner backend verifies callback
+8. Partner grants or reconciles app access according to its own session model
+```
+
+---
+
+## Current alpha status
+
+Implemented:
+
+* popup verification flow
+* popup auth flow
+* action-specific `hg.verify({ actionKey })`
+* action-specific `hg.auth({ actionKey })`
+* fallback behavior without `actionKey`
+* postMessage result delivery
+* timeout handling
+* user close detection
+* duplicate verify/auth call prevention
+* signed callback verification helper
+* full callback validation helper
+* ESM/CJS builds
+* TypeScript types
+* prepack build protection
+* prepublish typecheck/build protection
+
+Planned:
 
-This package currently exists to reserve the official namespace for future Human Gateway SDK releases.
+* iframe modal mode
+* redirect fallback
+* React helper
+* expanded usage/session events
+* public package release

package/dist/chunk-GJKDROWD.js

@@ -0,0 +1,2 @@
+var t=class extends Error{constructor(e,a){super(a),this.name="HumanGatewayError",this.code=e}},n=class extends Error{constructor(e,a){super(a),this.name="HumanGatewayCallbackError",this.code=e}};export{t as a,n as b};
+//# sourceMappingURL=chunk-GJKDROWD.js.map