@keytrace/claims 0.0.5

package/dist/verify.js

@@ -0,0 +1,143 @@
+import { resolveHandle, resolvePds, listClaimRecords, getRecordByUri } from "./atproto.js";
+import { verifyES256Signature } from "./crypto/signature.js";
+/**
+ * Verify all keytrace claims for a handle.
+ *
+ * @param handle The ATProto handle (e.g., "alice.bsky.social") or DID
+ * @param options Optional configuration
+ * @returns Verification results for all claims
+ */
+export async function getClaimsForHandle(handle, options) {
+    const did = await resolveHandle(handle, options);
+    const result = await getClaimsForDid(did, options);
+    return {
+        ...result,
+        handle: handle.startsWith("did:") ? undefined : handle,
+    };
+}
+/**
+ * Verify all keytrace claims for a DID.
+ *
+ * @param did The ATProto DID (e.g., "did:plc:abc123")
+ * @param options Optional configuration
+ * @returns Verification results for all claims
+ */
+export async function getClaimsForDid(did, options) {
+    // Resolve PDS for the user
+    const pdsUrl = await resolvePds(did, options);
+    // Fetch all claim records
+    let claimRecords;
+    try {
+        claimRecords = await listClaimRecords(pdsUrl, did, options);
+    }
+    catch {
+        // No claims found
+        return {
+            did,
+            claims: [],
+            summary: { total: 0, verified: 0, failed: 0 },
+        };
+    }
+    // Verify each claim
+    const claimResults = [];
+    for (const record of claimRecords) {
+        const result = await verifySingleClaim(did, record.uri, record.rkey, record.value, options);
+        claimResults.push(result);
+    }
+    return {
+        did,
+        claims: claimResults,
+        summary: {
+            total: claimResults.length,
+            verified: claimResults.filter((c) => c.verified).length,
+            failed: claimResults.filter((c) => !c.verified).length,
+        },
+    };
+}
+/**
+ * Verify a single claim's signature.
+ */
+async function verifySingleClaim(did, uri, rkey, claim, options) {
+    const steps = [];
+    try {
+        // Step 1: Validate claim structure
+        if (!claim.sig?.src || !claim.sig?.attestation || !claim.sig?.signedAt) {
+            steps.push({
+                step: "validate_claim",
+                success: false,
+                error: "Missing signature fields",
+            });
+            return buildResult(uri, rkey, claim, false, steps, "Missing signature fields");
+        }
+        steps.push({ step: "validate_claim", success: true, detail: "Claim structure valid" });
+        // Step 2: Fetch the signing key
+        let keyRecord;
+        try {
+            keyRecord = await getRecordByUri(claim.sig.src, options);
+            steps.push({ step: "fetch_key", success: true, detail: `Fetched key from ${claim.sig.src}` });
+        }
+        catch (err) {
+            const error = `Failed to fetch signing key: ${err instanceof Error ? err.message : String(err)}`;
+            steps.push({ step: "fetch_key", success: false, error });
+            return buildResult(uri, rkey, claim, false, steps, error);
+        }
+        // Step 3: Parse the public JWK
+        let publicJwk;
+        try {
+            publicJwk = JSON.parse(keyRecord.publicJwk);
+            if (publicJwk.kty !== "EC" || publicJwk.crv !== "P-256") {
+                throw new Error("Invalid key type");
+            }
+            steps.push({ step: "parse_key", success: true, detail: "Parsed ES256 public key" });
+        }
+        catch (err) {
+            const error = `Invalid public key format: ${err instanceof Error ? err.message : String(err)}`;
+            steps.push({ step: "parse_key", success: false, error });
+            return buildResult(uri, rkey, claim, false, steps, error);
+        }
+        // Step 4: Reconstruct the signed claim data
+        const signedData = {
+            did,
+            subject: claim.identity.subject,
+            type: claim.type,
+            verifiedAt: claim.sig.signedAt,
+        };
+        steps.push({
+            step: "reconstruct_data",
+            success: true,
+            detail: `Reconstructed signed data for ${claim.type}:${claim.identity.subject}`,
+        });
+        // Step 5: Verify the signature
+        const isValid = await verifyES256Signature(signedData, claim.sig.attestation, publicJwk);
+        if (isValid) {
+            steps.push({ step: "verify_signature", success: true, detail: "Signature verified" });
+            return buildResult(uri, rkey, claim, true, steps);
+        }
+        else {
+            steps.push({ step: "verify_signature", success: false, error: "Signature verification failed" });
+            return buildResult(uri, rkey, claim, false, steps, "Signature verification failed");
+        }
+    }
+    catch (err) {
+        const error = `Unexpected error: ${err instanceof Error ? err.message : String(err)}`;
+        steps.push({ step: "unknown", success: false, error });
+        return buildResult(uri, rkey, claim, false, steps, error);
+    }
+}
+/**
+ * Build a claim verification result.
+ */
+function buildResult(uri, rkey, claim, verified, steps, error) {
+    return {
+        uri,
+        rkey,
+        type: claim.type,
+        claimUri: claim.claimUri,
+        verified,
+        steps,
+        error,
+        identity: claim.identity,
+        claim,
+    };
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@keytrace/claims",
+  "version": "0.0.5",
+  "description": "Verify keytrace identity claims",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "type": "module",
+  "main": "./src/verify.ts",
+  "types": "./src/verify.ts",
+  "exports": {
+    ".": {
+      "types": "./src/verify.ts",
+      "default": "./src/verify.ts"
+    },
+    "./types": {
+      "types": "./src/types.ts",
+      "default": "./src/types.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/atproto.ts

@@ -0,0 +1,177 @@
+import type { ClaimRecord, KeyRecord, VerifyOptions } from "./types.js";
+import { PUBLIC_API_URL, PLC_DIRECTORY_URL, COLLECTION_NSID, DEFAULT_TIMEOUT } from "./constants.js";
+
+interface DidDocument {
+  id: string;
+  service?: Array<{
+    id: string;
+    type: string;
+    serviceEndpoint: string;
+  }>;
+}
+
+interface ListRecordsResponse {
+  records: Array<{
+    uri: string;
+    cid: string;
+    value: unknown;
+  }>;
+  cursor?: string;
+}
+
+interface GetRecordResponse {
+  uri: string;
+  cid: string;
+  value: unknown;
+}
+
+/**
+ * Fetch with timeout support
+ */
+async function fetchWithTimeout(url: string, options?: VerifyOptions): Promise<Response> {
+  const fetchFn = options?.fetch ?? globalThis.fetch;
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetchFn(url, { signal: controller.signal });
+    return response;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Resolve a handle to a DID using the public ATProto API.
+ */
+export async function resolveHandle(handle: string, options?: VerifyOptions): Promise<string> {
+  // If it's already a DID, return it
+  if (handle.startsWith("did:")) {
+    return handle;
+  }
+
+  const baseUrl = options?.publicApiUrl ?? PUBLIC_API_URL;
+  const url = `${baseUrl}/xrpc/com.atproto.identity.resolveHandle?handle=${encodeURIComponent(handle)}`;
+
+  const response = await fetchWithTimeout(url, options);
+  if (!response.ok) {
+    throw new Error(`Failed to resolve handle: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as { did: string };
+  return data.did;
+}
+
+/**
+ * Resolve the PDS endpoint from a DID document.
+ */
+export async function resolvePds(did: string, options?: VerifyOptions): Promise<string> {
+  const plcUrl = options?.plcDirectoryUrl ?? PLC_DIRECTORY_URL;
+
+  try {
+    let url: string;
+    if (did.startsWith("did:plc:")) {
+      url = `${plcUrl}/${did}`;
+    } else if (did.startsWith("did:web:")) {
+      const host = did.replace("did:web:", "").replaceAll(":", "/");
+      url = `https://${host}/.well-known/did.json`;
+    } else {
+      return PUBLIC_API_URL;
+    }
+
+    const response = await fetchWithTimeout(url, options);
+    if (!response.ok) {
+      return PUBLIC_API_URL;
+    }
+
+    const doc = (await response.json()) as DidDocument;
+    const pdsService = doc.service?.find((s) => s.id === "#atproto_pds" || s.type === "AtprotoPersonalDataServer");
+
+    return pdsService?.serviceEndpoint ?? PUBLIC_API_URL;
+  } catch {
+    return PUBLIC_API_URL;
+  }
+}
+
+/**
+ * List all keytrace claim records from a user's repo.
+ */
+export async function listClaimRecords(pdsUrl: string, did: string, options?: VerifyOptions): Promise<Array<{ uri: string; rkey: string; value: ClaimRecord }>> {
+  const claims: Array<{ uri: string; rkey: string; value: ClaimRecord }> = [];
+
+  try {
+    let cursor: string | undefined;
+    do {
+      const url = new URL(`${pdsUrl}/xrpc/com.atproto.repo.listRecords`);
+      url.searchParams.set("repo", did);
+      url.searchParams.set("collection", COLLECTION_NSID);
+      url.searchParams.set("limit", "100");
+      if (cursor) url.searchParams.set("cursor", cursor);
+
+      const response = await fetchWithTimeout(url.toString(), options);
+      if (!response.ok) {
+        // No records or repo not found
+        if (response.status === 400 || response.status === 404) {
+          break;
+        }
+        throw new Error(`Failed to list records: ${response.status}`);
+      }
+
+      const data = (await response.json()) as ListRecordsResponse;
+
+      for (const record of data.records) {
+        const rkey = parseAtUriRkey(record.uri);
+        claims.push({
+          uri: record.uri,
+          rkey,
+          value: record.value as ClaimRecord,
+        });
+      }
+
+      cursor = data.cursor;
+    } while (cursor);
+  } catch (err) {
+    // Silently handle errors - return whatever we got
+    if (claims.length === 0) {
+      throw err;
+    }
+  }
+
+  return claims;
+}
+
+/**
+ * Fetch a single record by AT URI.
+ */
+export async function getRecordByUri<T>(atUri: string, options?: VerifyOptions): Promise<T> {
+  const match = atUri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
+  if (!match) {
+    throw new Error(`Invalid AT URI: ${atUri}`);
+  }
+
+  const [, repo, collection, rkey] = match;
+  const pdsUrl = await resolvePds(repo, options);
+
+  const url = new URL(`${pdsUrl}/xrpc/com.atproto.repo.getRecord`);
+  url.searchParams.set("repo", repo);
+  url.searchParams.set("collection", collection);
+  url.searchParams.set("rkey", rkey);
+
+  const response = await fetchWithTimeout(url.toString(), options);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch record: ${response.status}`);
+  }
+
+  const data = (await response.json()) as GetRecordResponse;
+  return data.value as T;
+}
+
+/**
+ * Parse the rkey from an AT URI.
+ */
+function parseAtUriRkey(atUri: string): string {
+  const match = atUri.match(/^at:\/\/[^/]+\/[^/]+\/(.+)$/);
+  return match?.[1] ?? "";
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+export const PUBLIC_API_URL = "https://public.api.bsky.app";
+export const PLC_DIRECTORY_URL = "https://plc.directory";
+export const COLLECTION_NSID = "dev.keytrace.claim";
+export const KEY_COLLECTION_NSID = "dev.keytrace.key";
+export const DEFAULT_TIMEOUT = 10000;

package/src/crypto/base64url.ts

@@ -0,0 +1,29 @@
+/**
+ * Base64url decode a string to UTF-8 text.
+ */
+export function base64urlDecode(str: string): string {
+  const bytes = base64urlDecodeToBytes(str);
+  return new TextDecoder().decode(bytes);
+}
+
+/**
+ * Base64url decode a string to raw bytes.
+ */
+export function base64urlDecodeToBytes(str: string): Uint8Array {
+  // Add padding if needed
+  let padded = str;
+  const remainder = str.length % 4;
+  if (remainder === 2) padded += "==";
+  else if (remainder === 3) padded += "=";
+
+  // Convert URL-safe characters back to standard base64
+  const base64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+
+  // Decode - works in both browser and Node.js
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/crypto/canonicalize.ts

@@ -0,0 +1,74 @@
+/**
+ * Canonicalize a value according to RFC 8785 (JSON Canonicalization Scheme).
+ * https://datatracker.ietf.org/doc/html/rfc8785
+ *
+ * This ensures deterministic JSON output for cryptographic signing by:
+ * - Sorting object keys by UTF-16 code units
+ * - Serializing numbers per ES2020 Number.toString() (no -0, no NaN/Infinity)
+ * - No optional whitespace
+ * - Proper string escaping per RFC 8259
+ */
+export function canonicalize(data: unknown): string {
+  return serialize(data);
+}
+
+function serialize(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+
+  switch (typeof value) {
+    case "boolean":
+      return value ? "true" : "false";
+
+    case "number":
+      if (!Number.isFinite(value)) {
+        throw new Error("RFC 8785: Cannot serialize Infinity or NaN");
+      }
+      // RFC 8785 Section 3.2.2.3: -0 must be serialized as 0
+      if (Object.is(value, -0)) {
+        return "0";
+      }
+      // Use ES Number.toString() which produces RFC 8785 compliant output
+      return String(value);
+
+    case "string":
+      // JSON.stringify handles RFC 8259 string escaping
+      return JSON.stringify(value);
+
+    case "object":
+      if (Array.isArray(value)) {
+        return "[" + value.map(serialize).join(",") + "]";
+      }
+      return serializeObject(value as Record<string, unknown>);
+
+    default:
+      throw new Error(`RFC 8785: Cannot serialize value of type ${typeof value}`);
+  }
+}
+
+/**
+ * Serialize an object with keys sorted by UTF-16 code units per RFC 8785 Section 3.2.3.
+ */
+function serializeObject(obj: Record<string, unknown>): string {
+  // RFC 8785: Sort keys by comparing UTF-16 code units
+  const keys = Object.keys(obj).sort((a, b) => {
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+      const diff = a.charCodeAt(i) - b.charCodeAt(i);
+      if (diff !== 0) return diff;
+    }
+    return a.length - b.length;
+  });
+
+  const pairs: string[] = [];
+  for (const key of keys) {
+    const val = obj[key];
+    // Skip undefined values (not valid in JSON)
+    if (val !== undefined) {
+      pairs.push(JSON.stringify(key) + ":" + serialize(val));
+    }
+  }
+
+  return "{" + pairs.join(",") + "}";
+}

package/src/crypto/signature.ts

@@ -0,0 +1,36 @@
+import type { ES256PublicJwk, SignedClaimData } from "../types.js";
+import { canonicalize } from "./canonicalize.js";
+import { base64urlDecode, base64urlDecodeToBytes } from "./base64url.js";
+
+/**
+ * Verify a JWS ES256 signature using Web Crypto API.
+ *
+ * @param claimData The claim data that was signed
+ * @param jws The JWS compact serialization (header.payload.signature)
+ * @param publicJwk The P-256 public key as JWK
+ * @returns true if signature is valid, false otherwise
+ */
+export async function verifyES256Signature(claimData: SignedClaimData, jws: string, publicJwk: ES256PublicJwk): Promise<boolean> {
+  const parts = jws.split(".");
+  if (parts.length !== 3) return false;
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  // Verify payload matches expected canonical form
+  const expectedPayload = canonicalize(claimData as unknown as Record<string, unknown>);
+  const actualPayload = base64urlDecode(payloadB64);
+  if (actualPayload !== expectedPayload) return false;
+
+  // Import JWK as CryptoKey
+  const key = await crypto.subtle.importKey("jwk", { ...publicJwk, alg: "ES256", use: "sig" }, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
+
+  // Web Crypto expects raw signature bytes (R||S format) - which is what JWS ES256 uses
+  const signatureBytes = base64urlDecodeToBytes(signatureB64);
+  const signingInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+
+  // Create a fresh ArrayBuffer to satisfy TypeScript's strict BufferSource type
+  const signatureBuffer = new ArrayBuffer(signatureBytes.length);
+  new Uint8Array(signatureBuffer).set(signatureBytes);
+
+  return crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, key, signatureBuffer, signingInput);
+}

package/src/types.ts

@@ -0,0 +1,133 @@
+/**
+ * Identity metadata from a claim record
+ */
+export interface ClaimIdentity {
+  subject: string;
+  avatarUrl?: string;
+  profileUrl?: string;
+  displayName?: string;
+}
+
+/**
+ * Signature data from a claim record
+ */
+export interface ClaimSignature {
+  /** Key identifier (YYYY-MM-DD) */
+  kid: string;
+  /** AT URI to the signing key record */
+  src: string;
+  /** Timestamp when signed */
+  signedAt: string;
+  /** JWS compact serialization */
+  attestation: string;
+}
+
+/**
+ * Raw claim record from ATProto
+ */
+export interface ClaimRecord {
+  $type: "dev.keytrace.claim";
+  type: string;
+  claimUri: string;
+  identity: ClaimIdentity;
+  sig: ClaimSignature;
+  comment?: string;
+  createdAt: string;
+  prerelease?: boolean;
+}
+
+/**
+ * Public key record from keytrace service
+ */
+export interface KeyRecord {
+  $type: "dev.keytrace.key";
+  publicJwk: string;
+  validFrom: string;
+  validUntil: string;
+}
+
+/**
+ * Parsed JWK for P-256 public key
+ */
+export interface ES256PublicJwk {
+  kty: "EC";
+  crv: "P-256";
+  x: string;
+  y: string;
+}
+
+/**
+ * Claim data that is signed (canonical form)
+ */
+export interface SignedClaimData {
+  did: string;
+  subject: string;
+  type: string;
+  verifiedAt: string;
+}
+
+/**
+ * Verification step detail for debugging/auditing
+ */
+export interface VerificationStep {
+  step: string;
+  success: boolean;
+  detail?: string;
+  error?: string;
+}
+
+/**
+ * Result of verifying a single claim
+ */
+export interface ClaimVerificationResult {
+  /** AT URI of the claim record */
+  uri: string;
+  /** Record key */
+  rkey: string;
+  /** Claim type (github, dns, etc.) */
+  type: string;
+  /** The claim URI being verified */
+  claimUri: string;
+  /** Whether signature verification passed */
+  verified: boolean;
+  /** Verification steps performed */
+  steps: VerificationStep[];
+  /** Error message if verification failed */
+  error?: string;
+  /** Identity data (available regardless of verification status) */
+  identity: ClaimIdentity;
+  /** Full claim record */
+  claim: ClaimRecord;
+}
+
+/**
+ * Result of verifying all claims for a DID
+ */
+export interface VerificationResult {
+  /** The DID that was verified */
+  did: string;
+  /** Resolved handle (if available) */
+  handle?: string;
+  /** Array of claim verification results */
+  claims: ClaimVerificationResult[];
+  /** Summary statistics */
+  summary: {
+    total: number;
+    verified: number;
+    failed: number;
+  };
+}
+
+/**
+ * Options for verification
+ */
+export interface VerifyOptions {
+  /** Custom fetch function (defaults to globalThis.fetch) */
+  fetch?: typeof fetch;
+  /** Request timeout in ms (default: 10000) */
+  timeout?: number;
+  /** PLC directory URL (default: https://plc.directory) */
+  plcDirectoryUrl?: string;
+  /** Public ATProto API URL for handle resolution (default: https://public.api.bsky.app) */
+  publicApiUrl?: string;
+}