@auths-dev/sdk 0.0.1 → 0.1.0

package/Cargo.toml

@@ -0,0 +1,45 @@
+[package]
+name = "auths-node"
+version = "0.1.0"
+edition = "2024"
+description = "Node.js bindings for the Auths decentralized identity SDK"
+license = "Apache-2.0"
+publish = false
+
+[workspace]
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = { version = "3", default-features = false, features = ["napi4", "async", "tokio_rt", "serde-json"] }
+napi-derive = "3"
+
+# Core auths crates (same as auths-python)
+auths-sdk = { path = "../../crates/auths-sdk" }
+auths-core = { path = "../../crates/auths-core", features = ["keychain-file-fallback"] }
+auths-id = { path = "../../crates/auths-id" }
+auths-crypto = { path = "../../crates/auths-crypto" }
+auths-verifier = { path = "../../crates/auths-verifier" }
+auths-storage = { path = "../../crates/auths-storage", features = ["backend-git"] }
+auths-policy = { path = "../../crates/auths-policy" }
+auths-pairing-daemon = { path = "../../crates/auths-pairing-daemon" }
+auths-infra-git = { path = "../../crates/auths-infra-git" }
+
+# Utilities
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["sync", "net"] }
+reqwest = { version = "0.13.2", default-features = false, features = ["rustls", "json"] }
+hex = "0.4"
+chrono = "0.4"
+ring = "0.17"
+json-canon = "=0.1.3"
+sha2 = "0.10"
+uuid = { version = "1", features = ["v4"] }
+shellexpand = "3"
+url = "2"
+axum = "0.8"
+
+[build-dependencies]
+napi-build = "2"

package/README.md

@@ -1,7 +1,166 @@
-# @auths-dev/sdk
+# Auths Node SDK
 
-Auths SDK for decentralized identity management.
+Decentralized identity for developers and AI agents. Sign, verify, and manage cryptographic identities with Git-native storage.
 
-**This package is coming soon.** 
+## Install
 
-Visit [auths.dev](https://auths.dev) for more information.
+```bash
+npm install @auths-dev/sdk
+```
+
+## Quick start
+
+```typescript
+import { Auths, verifyAttestation } from '@auths-dev/sdk'
+
+const auths = new Auths()
+
+// Verify an attestation
+const result = verifyAttestation(attestationJson, publicKeyHex)
+console.log(result.valid) // true
+
+// Create an identity and sign
+const identity = auths.identities.create({ label: 'laptop' })
+const sig = auths.signAs({ message: Buffer.from('hello world'), identityDid: identity.did })
+console.log(sig.signature) // hex-encoded Ed25519 signature
+```
+
+## Identity management
+
+```typescript
+import { Auths } from '@auths-dev/sdk'
+
+const auths = new Auths({ repoPath: '~/.auths' })
+
+// Create a cryptographic identity
+const identity = auths.identities.create({ label: 'laptop' })
+console.log(identity.did) // did:keri:EBfd...
+
+// Provision an agent (for CI, MCP servers, etc.)
+const agent = auths.identities.delegateAgent({
+  identityDid: identity.did,
+  name: 'deploy-bot',
+  capabilities: ['sign'],
+})
+
+// Sign using the keychain-stored identity key
+const result = auths.signAs({
+  message: Buffer.from('hello world'),
+  identityDid: identity.did,
+})
+
+// Link and manage devices
+const device = auths.devices.link({
+  identityDid: identity.did,
+  capabilities: ['sign'],
+})
+auths.devices.revoke({
+  deviceDid: device.did,
+  identityDid: identity.did,
+  note: 'replaced',
+})
+```
+
+## Policy engine
+
+```typescript
+import { PolicyBuilder, evaluatePolicy } from '@auths-dev/sdk'
+
+// Build a standard policy
+const policy = PolicyBuilder.standard('sign_commit')
+
+// Evaluate against a context
+const decision = policy.evaluate({
+  issuer: 'did:keri:EOrg',
+  subject: 'did:key:zDevice',
+  capabilities: ['sign_commit'],
+})
+console.log(decision.allowed) // true
+
+// Compose complex policies
+const ciPolicy = new PolicyBuilder()
+  .notRevoked()
+  .notExpired()
+  .requireCapability('sign')
+  .requireAgent()
+  .requireRepo('org/repo')
+  .toJson()
+```
+
+## Organization management
+
+```typescript
+const org = auths.orgs.create({ label: 'my-team' })
+
+const member = auths.orgs.addMember({
+  orgDid: org.orgDid,
+  memberDid: devIdentity.did,
+  role: 'member',
+  memberPublicKeyHex: devIdentity.publicKey,
+})
+
+const members = auths.orgs.listMembers({ orgDid: org.orgDid })
+```
+
+## Verification
+
+```typescript
+import {
+  verifyAttestation,
+  verifyChain,
+  verifyAttestationWithCapability,
+} from '@auths-dev/sdk'
+
+// Single attestation
+const result = verifyAttestation(attestationJson, issuerPublicKeyHex)
+
+// Attestation chain
+const report = verifyChain(attestationChain, rootPublicKeyHex)
+console.log(report.status.statusType) // 'Valid' | 'Invalid' | ...
+
+// Capability-scoped verification
+const capResult = verifyAttestationWithCapability(
+  attestationJson, issuerPublicKeyHex, 'sign_commit'
+)
+```
+
+## Error handling
+
+```typescript
+import { Auths, VerificationError, CryptoError, NetworkError } from '@auths-dev/sdk'
+
+const auths = new Auths()
+try {
+  const result = auths.signAs({ message: data, identityDid: did })
+} catch (e) {
+  if (e instanceof CryptoError) {
+    console.log(e.code)    // 'key_not_found'
+    console.log(e.message) // 'No key found for identity...'
+  }
+  if (e instanceof NetworkError && e.shouldRetry) {
+    // safe to retry
+  }
+}
+```
+
+All errors inherit from `AuthsError` and carry `.code` and `.message`.
+
+## Configuration
+
+```typescript
+// Auto-discover (uses ~/.auths)
+const auths = new Auths()
+
+// Explicit repo path
+const auths = new Auths({ repoPath: '/path/to/identity-repo' })
+
+// With passphrase (or set AUTHS_PASSPHRASE env var)
+const auths = new Auths({ passphrase: 'my-secret' })
+
+// Headless / CI mode
+// Set AUTHS_KEYCHAIN_BACKEND=file for environments without a system keychain
+```
+
+## License
+
+Apache-2.0

package/__test__/client.spec.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest'
+import { Auths } from '../lib/client'
+import {
+  AuthsError,
+  VerificationError,
+  CryptoError,
+  KeychainError,
+  StorageError,
+  NetworkError,
+  IdentityError,
+  OrgError,
+  PairingError,
+} from '../lib/errors'
+
+describe('Auths client', () => {
+  it('instantiates with defaults', () => {
+    const auths = new Auths()
+    expect(auths.repoPath).toBe('~/.auths')
+    expect(auths.passphrase).toBeUndefined()
+  })
+
+  it('instantiates with custom config', () => {
+    const auths = new Auths({ repoPath: '/tmp/test-repo', passphrase: 'secret' })
+    expect(auths.repoPath).toBe('/tmp/test-repo')
+    expect(auths.passphrase).toBe('secret')
+  })
+
+  it('exposes all service properties', () => {
+    const auths = new Auths()
+    expect(auths.identities).toBeDefined()
+    expect(auths.devices).toBeDefined()
+    expect(auths.signing).toBeDefined()
+    expect(auths.orgs).toBeDefined()
+    expect(auths.trust).toBeDefined()
+    expect(auths.witnesses).toBeDefined()
+    expect(auths.attestations).toBeDefined()
+    expect(auths.artifacts).toBeDefined()
+    expect(auths.commits).toBeDefined()
+    expect(auths.audit).toBeDefined()
+    expect(auths.pairing).toBeDefined()
+  })
+})
+
+describe('error hierarchy', () => {
+  it('all error subclasses extend AuthsError', () => {
+    for (const Cls of [
+      VerificationError,
+      CryptoError,
+      KeychainError,
+      StorageError,
+      NetworkError,
+      IdentityError,
+      OrgError,
+      PairingError,
+    ]) {
+      const err = new Cls('test')
+      expect(err).toBeInstanceOf(AuthsError)
+      expect(err).toBeInstanceOf(Error)
+    }
+  })
+
+  it('AuthsError has code and message', () => {
+    const err = new AuthsError('something broke')
+    err.code = 'AUTHS_TEST'
+    expect(err.message).toBe('something broke')
+    expect(err.code).toBe('AUTHS_TEST')
+  })
+
+  it('NetworkError has shouldRetry', () => {
+    const err = new NetworkError('timeout')
+    expect(err.shouldRetry).toBe(true)
+  })
+
+  it('PairingError has shouldRetry', () => {
+    const err = new PairingError('session expired')
+    expect(err.shouldRetry).toBe(true)
+  })
+})

package/__test__/exports.spec.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest'
+import * as auths from '../lib/index'
+
+describe('top-level exports', () => {
+  it('exports Auths client', () => {
+    expect(auths.Auths).toBeDefined()
+  })
+
+  it('exports service classes', () => {
+    expect(auths.IdentityService).toBeDefined()
+    expect(auths.DeviceService).toBeDefined()
+    expect(auths.SigningService).toBeDefined()
+    expect(auths.OrgService).toBeDefined()
+    expect(auths.TrustService).toBeDefined()
+    expect(auths.WitnessService).toBeDefined()
+    expect(auths.AttestationService).toBeDefined()
+    expect(auths.ArtifactService).toBeDefined()
+    expect(auths.CommitService).toBeDefined()
+    expect(auths.AuditService).toBeDefined()
+    expect(auths.PairingService).toBeDefined()
+  })
+
+  it('exports PolicyBuilder and policy functions', () => {
+    expect(auths.PolicyBuilder).toBeDefined()
+    expect(auths.compilePolicy).toBeDefined()
+    expect(auths.evaluatePolicy).toBeDefined()
+  })
+
+  it('exports verification functions', () => {
+    expect(auths.verifyAttestation).toBeDefined()
+    expect(auths.verifyChain).toBeDefined()
+    expect(auths.verifyDeviceAuthorization).toBeDefined()
+    expect(auths.verifyAttestationWithCapability).toBeDefined()
+    expect(auths.verifyChainWithCapability).toBeDefined()
+    expect(auths.verifyAtTime).toBeDefined()
+    expect(auths.verifyAtTimeWithCapability).toBeDefined()
+    expect(auths.verifyChainWithWitnesses).toBeDefined()
+  })
+
+  it('exports error classes', () => {
+    expect(auths.AuthsError).toBeDefined()
+    expect(auths.VerificationError).toBeDefined()
+    expect(auths.CryptoError).toBeDefined()
+    expect(auths.KeychainError).toBeDefined()
+    expect(auths.StorageError).toBeDefined()
+    expect(auths.NetworkError).toBeDefined()
+    expect(auths.IdentityError).toBeDefined()
+    expect(auths.OrgError).toBeDefined()
+    expect(auths.PairingError).toBeDefined()
+    expect(auths.mapNativeError).toBeDefined()
+  })
+
+  it('exports version function', () => {
+    expect(auths.version).toBeDefined()
+    expect(typeof auths.version).toBe('function')
+  })
+})