@kynesyslabs/demosdk 2.6.0 → 2.7.0

package/build/keyserver/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Key Server Module
+ *
+ * Client for Key Server OAuth verification with DAHR attestation.
+ * Enables dApps to verify user ownership of GitHub/Discord accounts.
+ *
+ * @example
+ * ```typescript
+ * import { KeyServerClient } from "@kynesyslabs/demosdk/keyserver";
+ *
+ * const client = new KeyServerClient({
+ *     endpoint: "http://localhost:3030",
+ *     nodePubKey: nodePublicKey,
+ * });
+ *
+ * // Full verification flow
+ * const result = await client.verifyOAuth("github", {
+ *     onAuthUrl: (url) => window.open(url),
+ *     onPoll: (attempt, status) => console.log(`Poll ${attempt}: ${status}`),
+ * });
+ *
+ * console.log("Verified user:", result.user.username);
+ * console.log("Attestation:", result.attestation);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyOAuthAttestation = exports.verifyAttestation = exports.OAuthError = exports.KeyServerClient = void 0;
+var KeyServerClient_1 = require("./KeyServerClient");
+Object.defineProperty(exports, "KeyServerClient", { enumerable: true, get: function () { return KeyServerClient_1.KeyServerClient; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "OAuthError", { enumerable: true, get: function () { return errors_1.OAuthError; } });
+var verification_1 = require("./verification");
+Object.defineProperty(exports, "verifyAttestation", { enumerable: true, get: function () { return verification_1.verifyAttestation; } });
+Object.defineProperty(exports, "verifyOAuthAttestation", { enumerable: true, get: function () { return verification_1.verifyOAuthAttestation; } });
+//# sourceMappingURL=index.js.map

package/build/keyserver/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/keyserver/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAEH,qDAAoD;AAA3C,kHAAA,eAAe,OAAA;AACxB,mCAAsC;AAA7B,oGAAA,UAAU,OAAA;AACnB,+CAA2E;AAAlE,iHAAA,iBAAiB,OAAA;AAAE,sHAAA,sBAAsB,OAAA"}

package/build/keyserver/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Key Server OAuth Types
+ *
+ * Types for OAuth verification flow with DAHR attestation.
+ * Used by KeyServerClient to interact with the Key Server OAuth endpoints.
+ */
+/**
+ * Supported OAuth providers
+ */
+export type OAuthService = "github" | "discord";
+/**
+ * Options for initiating an OAuth flow
+ */
+export interface OAuthInitOptions {
+    /** Custom scopes to request (defaults to identity scopes) */
+    scopes?: string[];
+    /** Flow timeout in milliseconds (default: 600000 = 10min) */
+    timeout?: number;
+}
+/**
+ * Result from initiating an OAuth flow
+ */
+export interface OAuthInitResult {
+    /** Whether the initiation was successful */
+    success: boolean;
+    /** URL for user to visit to authorize */
+    authUrl: string;
+    /** State identifier for polling */
+    state: string;
+    /** Unix timestamp when this flow expires */
+    expiresAt: number;
+}
+/**
+ * Status of an OAuth flow
+ */
+export type OAuthStatus = "pending" | "completed" | "failed" | "expired";
+/**
+ * User identity information from OAuth provider
+ */
+export interface OAuthUserInfo {
+    /** OAuth provider */
+    service: OAuthService;
+    /** Provider's user ID */
+    providerId: string;
+    /** Provider's username */
+    username: string;
+    /** User email (if email scope was requested) */
+    email?: string;
+    /** User avatar URL */
+    avatarUrl?: string;
+    /** Unix timestamp when verification completed */
+    verifiedAt: number;
+}
+/**
+ * DAHR (Demos Attestation Hash Response) attestation
+ * Cryptographic proof that the Key Server performed the verification
+ */
+export interface DAHRAttestation {
+    /** SHA256 hash of the request payload */
+    requestHash: string;
+    /** SHA256 hash of the response payload */
+    responseHash: string;
+    /** Ed25519 signature over responseHash */
+    signature: {
+        type: "Ed25519";
+        data: string;
+    };
+    /** Attestation metadata */
+    metadata: {
+        /** Session identifier */
+        sessionId: string;
+        /** Unix timestamp of attestation */
+        timestamp: number;
+        /** Key Server's public key (hex) */
+        keyServerPubKey: string;
+        /** Node's public key (hex) */
+        nodePubKey: string;
+        /** Key Server version */
+        version: string;
+    };
+}
+/**
+ * Result from polling an OAuth flow
+ */
+export interface OAuthPollResult {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Current status of the OAuth flow */
+    status: OAuthStatus;
+    /** User info (only present when status is "completed") */
+    result?: OAuthUserInfo;
+    /** DAHR attestation (only present when status is "completed") */
+    attestation?: DAHRAttestation;
+    /** Error details (only present when status is "failed" or "expired") */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Options for the convenience verifyOAuth method
+ */
+export interface OAuthVerifyOptions extends OAuthInitOptions {
+    /**
+     * Called when auth URL is ready - dApp should display this to user
+     */
+    onAuthUrl?: (authUrl: string, state: string) => void;
+    /**
+     * Polling interval in milliseconds (default: 2000)
+     */
+    pollInterval?: number;
+    /**
+     * Called on each poll attempt (for UI feedback)
+     */
+    onPoll?: (attempt: number, status: OAuthStatus) => void;
+}
+/**
+ * Result from the convenience verifyOAuth method
+ */
+export interface OAuthVerificationResult {
+    /** Whether verification was successful */
+    success: boolean;
+    /** Verified user information */
+    user: OAuthUserInfo;
+    /** DAHR attestation proving the verification */
+    attestation: DAHRAttestation;
+}
+/**
+ * Key Server client configuration
+ */
+export interface KeyServerClientConfig {
+    /** Key Server endpoint URL */
+    endpoint: string;
+    /** Node's public key (hex-encoded Ed25519) */
+    nodePubKey: string;
+}
+/**
+ * Response from GET /oauth/providers
+ */
+export interface OAuthProvidersResponse {
+    success: boolean;
+    providers?: OAuthService[];
+    error?: {
+        code: string;
+        message: string;
+    };
+}

package/build/keyserver/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Key Server OAuth Types
+ *
+ * Types for OAuth verification flow with DAHR attestation.
+ * Used by KeyServerClient to interact with the Key Server OAuth endpoints.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/build/keyserver/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/keyserver/types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/build/keyserver/verification.d.ts

@@ -0,0 +1,79 @@
+/**
+ * DAHR Attestation Verification Utilities
+ *
+ * Provides cryptographic verification of Key Server attestations.
+ * Allows consuming apps to independently verify that the Key Server
+ * actually performed the OAuth verification.
+ */
+import type { DAHRAttestation, OAuthVerificationResult } from "./types";
+/**
+ * Options for attestation verification
+ */
+export interface VerifyAttestationOptions {
+    /**
+     * Maximum age of attestation in milliseconds (default: 1 hour)
+     * Set to 0 to disable timestamp validation
+     */
+    maxAge?: number;
+    /**
+     * Expected node public key (optional additional validation)
+     */
+    expectedNodePubKey?: string;
+}
+/**
+ * Result of attestation verification
+ */
+export interface AttestationVerificationResult {
+    /** Whether the attestation is valid */
+    valid: boolean;
+    /** Reason for failure (if invalid) */
+    reason?: string;
+    /** Attestation metadata for logging/auditing */
+    metadata?: {
+        sessionId: string;
+        timestamp: number;
+        keyServerPubKey: string;
+        nodePubKey: string;
+        version: string;
+    };
+}
+/**
+ * Verify a DAHR attestation from Key Server
+ *
+ * This function verifies:
+ * 1. The Ed25519 signature is valid for the responseHash
+ * 2. The signature was made by the expected Key Server public key
+ * 3. The attestation is not expired (optional)
+ * 4. The node public key matches expected (optional)
+ *
+ * @param attestation - The DAHR attestation to verify
+ * @param keyServerPubKey - Expected Key Server public key (hex-encoded)
+ * @param options - Additional verification options
+ * @returns Verification result with validity and reason
+ *
+ * @example
+ * ```typescript
+ * const result = await client.verifyOAuth("github", { ... });
+ *
+ * const verification = verifyAttestation(
+ *     result.attestation,
+ *     KNOWN_KEY_SERVER_PUBKEY,
+ * );
+ *
+ * if (!verification.valid) {
+ *     console.error("Attestation invalid:", verification.reason);
+ * }
+ * ```
+ */
+export declare function verifyAttestation(attestation: DAHRAttestation, keyServerPubKey: string, options?: VerifyAttestationOptions): AttestationVerificationResult;
+/**
+ * Verify attestation from a full OAuth verification result
+ *
+ * Convenience wrapper that extracts the attestation from the result.
+ *
+ * @param result - The OAuth verification result
+ * @param keyServerPubKey - Expected Key Server public key (hex-encoded)
+ * @param options - Additional verification options
+ * @returns Verification result
+ */
+export declare function verifyOAuthAttestation(result: OAuthVerificationResult, keyServerPubKey: string, options?: VerifyAttestationOptions): AttestationVerificationResult;

package/build/keyserver/verification.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * DAHR Attestation Verification Utilities
+ *
+ * Provides cryptographic verification of Key Server attestations.
+ * Allows consuming apps to independently verify that the Key Server
+ * actually performed the OAuth verification.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyAttestation = verifyAttestation;
+exports.verifyOAuthAttestation = verifyOAuthAttestation;
+const encryption_1 = require("../encryption");
+/**
+ * Verify a DAHR attestation from Key Server
+ *
+ * This function verifies:
+ * 1. The Ed25519 signature is valid for the responseHash
+ * 2. The signature was made by the expected Key Server public key
+ * 3. The attestation is not expired (optional)
+ * 4. The node public key matches expected (optional)
+ *
+ * @param attestation - The DAHR attestation to verify
+ * @param keyServerPubKey - Expected Key Server public key (hex-encoded)
+ * @param options - Additional verification options
+ * @returns Verification result with validity and reason
+ *
+ * @example
+ * ```typescript
+ * const result = await client.verifyOAuth("github", { ... });
+ *
+ * const verification = verifyAttestation(
+ *     result.attestation,
+ *     KNOWN_KEY_SERVER_PUBKEY,
+ * );
+ *
+ * if (!verification.valid) {
+ *     console.error("Attestation invalid:", verification.reason);
+ * }
+ * ```
+ */
+function verifyAttestation(attestation, keyServerPubKey, options) {
+    const maxAge = options?.maxAge ?? 3600000; // 1 hour default
+    // Validate attestation structure
+    if (!attestation || !attestation.signature || !attestation.metadata) {
+        return {
+            valid: false,
+            reason: "Invalid attestation structure",
+        };
+    }
+    // Check signature type
+    if (attestation.signature.type !== "Ed25519") {
+        return {
+            valid: false,
+            reason: `Unsupported signature type: ${attestation.signature.type}`,
+        };
+    }
+    // Check Key Server public key matches
+    if (attestation.metadata.keyServerPubKey !== keyServerPubKey) {
+        return {
+            valid: false,
+            reason: "Key Server public key mismatch",
+            metadata: attestation.metadata,
+        };
+    }
+    // Check node public key if expected
+    if (options?.expectedNodePubKey &&
+        attestation.metadata.nodePubKey !== options.expectedNodePubKey) {
+        return {
+            valid: false,
+            reason: "Node public key mismatch",
+            metadata: attestation.metadata,
+        };
+    }
+    // Check timestamp if maxAge is set
+    if (maxAge > 0) {
+        const age = Date.now() - attestation.metadata.timestamp;
+        if (age > maxAge) {
+            return {
+                valid: false,
+                reason: `Attestation expired (age: ${Math.round(age / 1000)}s, max: ${Math.round(maxAge / 1000)}s)`,
+                metadata: attestation.metadata,
+            };
+        }
+    }
+    // Verify Ed25519 signature over responseHash
+    try {
+        const isValid = encryption_1.Cryptography.ed25519.verify(attestation.responseHash, hexToBuffer(attestation.signature.data), hexToBuffer(keyServerPubKey));
+        if (!isValid) {
+            return {
+                valid: false,
+                reason: "Signature verification failed",
+                metadata: attestation.metadata,
+            };
+        }
+        return {
+            valid: true,
+            metadata: attestation.metadata,
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            reason: `Signature verification error: ${error.message}`,
+            metadata: attestation.metadata,
+        };
+    }
+}
+/**
+ * Verify attestation from a full OAuth verification result
+ *
+ * Convenience wrapper that extracts the attestation from the result.
+ *
+ * @param result - The OAuth verification result
+ * @param keyServerPubKey - Expected Key Server public key (hex-encoded)
+ * @param options - Additional verification options
+ * @returns Verification result
+ */
+function verifyOAuthAttestation(result, keyServerPubKey, options) {
+    if (!result.attestation) {
+        return {
+            valid: false,
+            reason: "No attestation in result",
+        };
+    }
+    return verifyAttestation(result.attestation, keyServerPubKey, options);
+}
+/**
+ * Convert hex string to Buffer for cryptographic operations
+ */
+function hexToBuffer(hex) {
+    // Remove 0x prefix if present
+    const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
+    return Buffer.from(cleanHex, "hex");
+}
+//# sourceMappingURL=verification.js.map

package/build/keyserver/verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.js","sourceRoot":"","sources":["../../../src/keyserver/verification.ts"],"names":[],"mappings":"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"}

package/build/types/abstraction/index.d.ts

@@ -69,9 +69,13 @@ export interface Web2CoreTargetIdentityPayload {
     userId: string;
     referralCode?: string;
 }
-export interface InferFromGithubOAuthPayload extends Web2CoreTargetIdentityPayload {
+type GistProofUrl = `https://gist.github.com/${string}/${string}`;
+type RawGistProofUrl = `https://gist.githubusercontent.com/${string}/${string}`;
+type RawGithubProofUrl = `https://raw.githubusercontent.com/${string}/${string}`;
+export type GithubProof = RawGistProofUrl | GistProofUrl | RawGithubProofUrl;
+export interface InferFromGithubPayload extends Web2CoreTargetIdentityPayload {
     context: "github";
-    proof: string;
+    proof: GithubProof;
 }
 export type XProof = `https://x.com/${string}/${string}`;
 export type TwitterProof = XProof;
@@ -126,7 +130,7 @@ export interface BaseWeb2IdentityPayload {
 }
 export interface Web2IdentityAssignPayload extends BaseWeb2IdentityPayload {
     method: "web2_identity_assign";
-    payload: InferFromGithubOAuthPayload | InferFromTwitterPayload | InferFromTelegramPayload | InferFromDiscordPayload;
+    payload: InferFromGithubPayload | InferFromTwitterPayload | InferFromTelegramPayload | InferFromDiscordPayload;
 }
 export interface Web2IdentityRemovePayload extends BaseWeb2IdentityPayload {
     method: "web2_identity_remove";
@@ -233,3 +237,4 @@ export interface FindDemosIdByWeb3IdentityQuery {
     chain: string;
     address: string;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kynesyslabs/demosdk",
-    "version": "2.6.0",
+    "version": "2.7.0",
     "description": "Demosdk is a JavaScript/TypeScript SDK that provides a unified interface for interacting with Demos network",
     "main": "build/index.js",
     "types": "build/index.d.ts",
@@ -37,7 +37,8 @@
         "./storage": "./build/storage/index.js",
         "./d402": "./build/d402/index.js",
         "./d402/server": "./build/d402/server/index.js",
-        "./d402/client": "./build/d402/client/index.js"
+        "./d402/client": "./build/d402/client/index.js",
+        "./keyserver": "./build/keyserver/index.js"
     },
     "scripts": {
         "postinstall": "cp .github/hooks/pre-commit .git/hooks/pre-commit 2>/dev/null && chmod +x .git/hooks/pre-commit 2>/dev/null || true",