@auths-dev/sdk 0.0.1 → 0.1.0

package/lib/verify.ts

@@ -0,0 +1,241 @@
+import native from './native'
+import type { NapiVerificationResult, NapiVerificationReport } from './native'
+import { mapNativeError, VerificationError } from './errors'
+
+/** Result of verifying a single attestation. */
+export interface VerificationResult {
+  /** Whether the attestation is valid. */
+  valid: boolean
+  /** Error message if verification failed, or `null`. */
+  error?: string | null
+  /** Machine-readable error code, or `null`. */
+  errorCode?: string | null
+}
+
+/** Status summary of a chain verification. */
+export interface VerificationStatus {
+  /** Status type: `'Valid'`, `'Invalid'`, `'Expired'`, etc. */
+  statusType: string
+  /** Timestamp context for the status, or `null`. */
+  at?: string | null
+  /** Chain step where verification failed, or `null`. */
+  step?: number | null
+  /** DID of the missing link in the chain, or `null`. */
+  missingLink?: string | null
+  /** Number of required witnesses, or `null`. */
+  required?: number | null
+  /** Number of verified witnesses, or `null`. */
+  verified?: number | null
+}
+
+/** A single link in a verified attestation chain. */
+export interface ChainLink {
+  /** DID of the issuer at this link. */
+  issuer: string
+  /** DID of the subject at this link. */
+  subject: string
+  /** Whether this link verified successfully. */
+  valid: boolean
+  /** Error message if this link failed, or `null`. */
+  error?: string | null
+}
+
+/** Full report from a chain verification. */
+export interface VerificationReport {
+  /** Overall verification status. */
+  status: VerificationStatus
+  /** Individual chain link results. */
+  chain: ChainLink[]
+  /** Non-fatal warnings encountered during verification. */
+  warnings: string[]
+}
+
+/** Public key of a witness node. */
+export interface WitnessKey {
+  /** DID of the witness. */
+  did: string
+  /** Hex-encoded Ed25519 public key of the witness. */
+  publicKeyHex: string
+}
+
+/** Configuration for witness-backed chain verification. */
+export interface WitnessConfig {
+  /** JSON-serialized witness receipts. */
+  receipts: string[]
+  /** Witness public keys. */
+  keys: WitnessKey[]
+  /** Minimum number of witness receipts required. */
+  threshold: number
+}
+
+/**
+ * Verifies a single attestation against an issuer's public key.
+ *
+ * @param attestationJson - JSON-serialized attestation.
+ * @param issuerPkHex - Hex-encoded Ed25519 public key of the issuer.
+ * @returns The verification result.
+ * @throws {@link VerificationError} if verification encounters an error.
+ *
+ * @example
+ * ```typescript
+ * import { verifyAttestation } from '@auths-dev/sdk'
+ *
+ * const result = await verifyAttestation(attestationJson, publicKeyHex)
+ * console.log(result.valid) // true
+ * ```
+ */
+export async function verifyAttestation(attestationJson: string, issuerPkHex: string): Promise<VerificationResult> {
+  try {
+    return await native.verifyAttestation(attestationJson, issuerPkHex)
+  } catch (err) {
+    throw mapNativeError(err, VerificationError)
+  }
+}
+
+/**
+ * Verifies a single attestation with a required capability check.
+ *
+ * @param attestationJson - JSON-serialized attestation.
+ * @param issuerPkHex - Hex-encoded Ed25519 public key of the issuer.
+ * @param requiredCapability - Capability the attestation must grant.
+ * @returns The verification result.
+ * @throws {@link VerificationError} if verification fails.
+ */
+export async function verifyAttestationWithCapability(attestationJson: string, issuerPkHex: string, requiredCapability: string): Promise<VerificationResult> {
+  try {
+    return await native.verifyAttestationWithCapability(attestationJson, issuerPkHex, requiredCapability)
+  } catch (err) {
+    throw mapNativeError(err, VerificationError)
+  }
+}
+
+/**
+ * Verifies an attestation chain from leaf to root.
+ *
+ * @param attestationsJson - Array of JSON-serialized attestations (leaf to root).
+ * @param rootPkHex - Hex-encoded Ed25519 public key of the root identity.
+ * @returns The verification report with chain link details.
+ * @throws {@link VerificationError} if verification encounters an error.
+ *
+ * @example
+ * ```typescript
+ * import { verifyChain } from '@auths-dev/sdk'
+ *
+ * const report = await verifyChain(attestationChain, rootPublicKeyHex)
+ * console.log(report.status.statusType) // 'Valid'
+ * ```
+ */
+export async function verifyChain(attestationsJson: string[], rootPkHex: string): Promise<VerificationReport> {
+  try {
+    return await native.verifyChain(attestationsJson, rootPkHex)
+  } catch (err) {
+    throw mapNativeError(err, VerificationError)
+  }
+}
+
+/**
+ * Verifies an attestation chain with a required capability at the leaf.
+ *
+ * @param attestationsJson - Array of JSON-serialized attestations (leaf to root).
+ * @param rootPkHex - Hex-encoded Ed25519 public key of the root identity.
+ * @param requiredCapability - Capability the leaf attestation must grant.
+ * @returns The verification report.
+ * @throws {@link VerificationError} if verification fails.
+ */
+export async function verifyChainWithCapability(attestationsJson: string[], rootPkHex: string, requiredCapability: string): Promise<VerificationReport> {
+  try {
+    return await native.verifyChainWithCapability(attestationsJson, rootPkHex, requiredCapability)
+  } catch (err) {
+    throw mapNativeError(err, VerificationError)
+  }
+}
+
+/**
+ * Verifies that a device is authorized by an identity through an attestation chain.
+ *
+ * @param identityDid - DID of the authorizing identity.
+ * @param deviceDid - DID of the device to verify.
+ * @param attestationsJson - Array of JSON-serialized attestations.
+ * @param identityPkHex - Hex-encoded Ed25519 public key of the identity.
+ * @returns The verification report.
+ * @throws {@link VerificationError} if verification fails.
+ */
+export async function verifyDeviceAuthorization(identityDid: string, deviceDid: string, attestationsJson: string[], identityPkHex: string): Promise<VerificationReport> {
+  try {
+    return await native.verifyDeviceAuthorization(identityDid, deviceDid, attestationsJson, identityPkHex)
+  } catch (err) {
+    throw mapNativeError(err, VerificationError)
+  }
+}
+
+/**
+ * Verifies a single attestation at a specific point in time.
+ *
+ * @param attestationJson - JSON-serialized attestation.
+ * @param issuerPkHex - Hex-encoded Ed25519 public key of the issuer.
+ * @param atRfc3339 - RFC 3339 timestamp to verify at.
+ * @returns The verification result.
+ * @throws {@link VerificationError} if verification fails.
+ */
+export async function verifyAtTime(attestationJson: string, issuerPkHex: string, atRfc3339: string): Promise<VerificationResult> {
+  try {
+    return await native.verifyAtTime(attestationJson, issuerPkHex, atRfc3339)
+  } catch (err) {
+    throw mapNativeError(err, VerificationError)
+  }
+}
+
+/**
+ * Verifies an attestation at a specific time with a required capability.
+ *
+ * @param attestationJson - JSON-serialized attestation.
+ * @param issuerPkHex - Hex-encoded Ed25519 public key of the issuer.
+ * @param atRfc3339 - RFC 3339 timestamp to verify at.
+ * @param requiredCapability - Capability the attestation must grant.
+ * @returns The verification result.
+ * @throws {@link VerificationError} if verification fails.
+ */
+export async function verifyAtTimeWithCapability(attestationJson: string, issuerPkHex: string, atRfc3339: string, requiredCapability: string): Promise<VerificationResult> {
+  try {
+    return await native.verifyAtTimeWithCapability(attestationJson, issuerPkHex, atRfc3339, requiredCapability)
+  } catch (err) {
+    throw mapNativeError(err, VerificationError)
+  }
+}
+
+/**
+ * Verifies an attestation chain with witness receipt validation.
+ *
+ * @param attestationsJson - Array of JSON-serialized attestations (leaf to root).
+ * @param rootPkHex - Hex-encoded Ed25519 public key of the root identity.
+ * @param witnesses - Witness configuration with receipts, keys, and threshold.
+ * @returns The verification report.
+ * @throws {@link VerificationError} if verification fails.
+ *
+ * @example
+ * ```typescript
+ * import { verifyChainWithWitnesses } from '@auths-dev/sdk'
+ *
+ * const report = await verifyChainWithWitnesses(chain, rootKey, {
+ *   receipts: witnessReceipts,
+ *   keys: [{ did: witnessDid, publicKeyHex: witnessKey }],
+ *   threshold: 1,
+ * })
+ * ```
+ */
+export async function verifyChainWithWitnesses(attestationsJson: string[], rootPkHex: string, witnesses: WitnessConfig): Promise<VerificationReport> {
+  const keysJson = witnesses.keys.map(k =>
+    JSON.stringify({ did: k.did, public_key_hex: k.publicKeyHex }),
+  )
+  try {
+    return await native.verifyChainWithWitnesses(
+      attestationsJson,
+      rootPkHex,
+      witnesses.receipts,
+      keysJson,
+      witnesses.threshold,
+    )
+  } catch (err) {
+    throw mapNativeError(err, VerificationError)
+  }
+}

package/lib/witness.ts

@@ -0,0 +1,91 @@
+import native from './native'
+import { mapNativeError, StorageError } from './errors'
+import type { Auths } from './client'
+
+/** A witness node entry in the local registry. */
+export interface WitnessEntry {
+  /** URL of the witness endpoint. */
+  url: string
+  /** DID of the witness, or `null` if not yet resolved. */
+  did: string | null
+  /** Optional label for the witness. */
+  label: string | null
+}
+
+/** Options for {@link WitnessService.add}. */
+export interface AddWitnessOptions {
+  /** URL of the witness endpoint (e.g. `'http://witness.example.com:3333'`). */
+  url: string
+  /** Optional label for the witness. */
+  label?: string
+}
+
+/**
+ * Manages witness nodes for receipt-based verification.
+ *
+ * Access via {@link Auths.witnesses}.
+ *
+ * @example
+ * ```typescript
+ * auths.witnesses.add({ url: 'http://witness.example.com:3333' })
+ * const witnesses = auths.witnesses.list()
+ * ```
+ */
+export class WitnessService {
+  constructor(private client: Auths) {}
+
+  /**
+   * Adds a witness node. Idempotent — adding the same URL twice is a no-op.
+   *
+   * @param opts - Witness options.
+   * @returns The witness entry.
+   * @throws {@link StorageError} if the operation fails.
+   *
+   * @example
+   * ```typescript
+   * const w = auths.witnesses.add({ url: 'http://witness.example.com:3333' })
+   * console.log(w.url) // http://witness.example.com:3333
+   * ```
+   */
+  add(opts: AddWitnessOptions): WitnessEntry {
+    try {
+      const result = native.addWitness(opts.url, this.client.repoPath, opts.label ?? null)
+      return {
+        url: result.url,
+        did: result.did ?? null,
+        label: result.label ?? null,
+      }
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+
+  /**
+   * Removes a witness by URL.
+   *
+   * @param url - URL of the witness to remove.
+   * @throws {@link StorageError} if the operation fails.
+   */
+  remove(url: string): void {
+    try {
+      native.removeWitness(url, this.client.repoPath)
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+
+  /**
+   * Lists all registered witnesses.
+   *
+   * @returns Array of witness entries.
+   * @throws {@link StorageError} if the operation fails.
+   */
+  list(): WitnessEntry[] {
+    try {
+      const json = native.listWitnesses(this.client.repoPath)
+      return JSON.parse(json)
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+}

package/npm/darwin-arm64/README.md

@@ -0,0 +1,3 @@
+# `@auths-dev/sdk-darwin-arm64`
+
+This is the **aarch64-apple-darwin** binary for `@auths-dev/sdk`

package/npm/darwin-arm64/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@auths-dev/sdk-darwin-arm64",
+  "version": "0.1.0",
+  "cpu": [
+    "arm64"
+  ],
+  "main": "auths.darwin-arm64.node",
+  "files": [
+    "auths.darwin-arm64.node"
+  ],
+  "description": "Node.js bindings for the Auths decentralized identity SDK",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/auths-dev/auths"
+  },
+  "os": [
+    "darwin"
+  ]
+}

package/npm/linux-arm64-gnu/README.md

@@ -0,0 +1,3 @@
+# `@auths-dev/sdk-linux-arm64-gnu`
+
+This is the **aarch64-unknown-linux-gnu** binary for `@auths-dev/sdk`

package/npm/linux-arm64-gnu/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@auths-dev/sdk-linux-arm64-gnu",
+  "version": "0.1.0",
+  "cpu": [
+    "arm64"
+  ],
+  "main": "auths.linux-arm64-gnu.node",
+  "files": [
+    "auths.linux-arm64-gnu.node"
+  ],
+  "description": "Node.js bindings for the Auths decentralized identity SDK",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/auths-dev/auths"
+  },
+  "os": [
+    "linux"
+  ],
+  "libc": [
+    "glibc"
+  ]
+}

package/npm/linux-x64-gnu/README.md

@@ -0,0 +1,3 @@
+# `@auths-dev/sdk-linux-x64-gnu`
+
+This is the **x86_64-unknown-linux-gnu** binary for `@auths-dev/sdk`

package/npm/linux-x64-gnu/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@auths-dev/sdk-linux-x64-gnu",
+  "version": "0.1.0",
+  "cpu": [
+    "x64"
+  ],
+  "main": "auths.linux-x64-gnu.node",
+  "files": [
+    "auths.linux-x64-gnu.node"
+  ],
+  "description": "Node.js bindings for the Auths decentralized identity SDK",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/auths-dev/auths"
+  },
+  "os": [
+    "linux"
+  ],
+  "libc": [
+    "glibc"
+  ]
+}

package/npm/win32-arm64-msvc/README.md

@@ -0,0 +1,3 @@
+# `@auths-dev/sdk-win32-arm64-msvc`
+
+This is the **aarch64-pc-windows-msvc** binary for `@auths-dev/sdk`

package/npm/win32-arm64-msvc/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@auths-dev/sdk-win32-arm64-msvc",
+  "version": "0.1.0",
+  "cpu": [
+    "arm64"
+  ],
+  "main": "auths.win32-arm64-msvc.node",
+  "files": [
+    "auths.win32-arm64-msvc.node"
+  ],
+  "description": "Node.js bindings for the Auths decentralized identity SDK",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/auths-dev/auths"
+  },
+  "os": [
+    "win32"
+  ]
+}

package/npm/win32-x64-msvc/README.md

@@ -0,0 +1,3 @@
+# `@auths-dev/sdk-win32-x64-msvc`
+
+This is the **x86_64-pc-windows-msvc** binary for `@auths-dev/sdk`

package/npm/win32-x64-msvc/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@auths-dev/sdk-win32-x64-msvc",
+  "version": "0.1.0",
+  "cpu": [
+    "x64"
+  ],
+  "main": "auths.win32-x64-msvc.node",
+  "files": [
+    "auths.win32-x64-msvc.node"
+  ],
+  "description": "Node.js bindings for the Auths decentralized identity SDK",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/auths-dev/auths"
+  },
+  "os": [
+    "win32"
+  ]
+}

package/package.json

@@ -1,21 +1,56 @@
 {
   "name": "@auths-dev/sdk",
-  "version": "0.0.1",
-  "description": "Auths SDK for decentralized identity management — coming soon",
-  "main": "index.js",
-  "keywords": [
-    "auths",
-    "identity",
-    "decentralized-identity",
-    "did",
-    "keri",
-    "sdk"
-  ],
-  "author": "auths-dev",
-  "license": "MIT",
-  "homepage": "https://auths.dev",
+  "version": "0.1.0",
+  "description": "Node.js bindings for the Auths decentralized identity SDK",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/auths-dev/auths.git"
+    "url": "https://github.com/auths-dev/auths"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "napi": {
+    "binaryName": "auths",
+    "targets": [
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-pc-windows-msvc",
+      "aarch64-pc-windows-msvc"
+    ]
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "prepublishOnly": "napi prepublish -t npm --no-gh-release",
+    "docs": "typedoc",
+    "test": "vitest run",
+    "universal": "napi universal -t darwin"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0",
+    "@types/node": "^25.3.5",
+    "typedoc": "^0.28.17",
+    "typedoc-plugin-markdown": "^4.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "@auths-dev/sdk-darwin-arm64": "0.1.0",
+    "@auths-dev/sdk-linux-x64-gnu": "0.1.0",
+    "@auths-dev/sdk-linux-arm64-gnu": "0.1.0",
+    "@auths-dev/sdk-win32-x64-msvc": "0.1.0",
+    "@auths-dev/sdk-win32-arm64-msvc": "0.1.0"
   }
-}
+}