@auths-dev/sdk 0.0.1 → 0.1.0

package/lib/artifacts.ts

@@ -0,0 +1,124 @@
+import native from './native'
+import { mapNativeError, CryptoError } from './errors'
+import type { Auths } from './client'
+
+/** Result of signing an artifact. */
+export interface ArtifactResult {
+  /** JSON-serialized attestation for the signed artifact. */
+  attestationJson: string
+  /** Unique resource identifier of the attestation. */
+  rid: string
+  /** Content digest (hash) of the artifact. */
+  digest: string
+  /** Size of the artifact in bytes. */
+  fileSize: number
+}
+
+/** Options for {@link ArtifactService.sign}. */
+export interface SignArtifactOptions {
+  /** Path to the file to sign. */
+  filePath: string
+  /** DID of the identity to sign with. */
+  identityDid: string
+  /** Optional expiration in days. */
+  expiresInDays?: number
+  /** Optional note attached to the attestation. */
+  note?: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/** Options for {@link ArtifactService.signBytes}. */
+export interface SignArtifactBytesOptions {
+  /** Raw bytes to sign. */
+  data: Buffer
+  /** DID of the identity to sign with. */
+  identityDid: string
+  /** Optional expiration in days. */
+  expiresInDays?: number
+  /** Optional note attached to the attestation. */
+  note?: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/**
+ * Signs artifacts (files or raw bytes) to produce verifiable attestations.
+ *
+ * Access via {@link Auths.artifacts}.
+ *
+ * @example
+ * ```typescript
+ * const result = auths.artifacts.sign({
+ *   filePath: './release.tar.gz',
+ *   identityDid: identity.did,
+ * })
+ * console.log(result.digest) // content hash
+ * ```
+ */
+export class ArtifactService {
+  constructor(private client: Auths) {}
+
+  /**
+   * Signs a file at the given path.
+   *
+   * @param opts - Signing options.
+   * @returns The artifact attestation with digest and metadata.
+   * @throws {@link CryptoError} if signing fails.
+   *
+   * @example
+   * ```typescript
+   * const result = auths.artifacts.sign({
+   *   filePath: './build/app.wasm',
+   *   identityDid: identity.did,
+   *   expiresInDays: 365,
+   * })
+   * ```
+   */
+  sign(opts: SignArtifactOptions): ArtifactResult {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      return native.signArtifact(
+        opts.filePath,
+        opts.identityDid,
+        this.client.repoPath,
+        pp,
+        opts.expiresInDays ?? null,
+        opts.note ?? null,
+      )
+    } catch (err) {
+      throw mapNativeError(err, CryptoError)
+    }
+  }
+
+  /**
+   * Signs raw bytes (e.g. an in-memory buffer).
+   *
+   * @param opts - Signing options.
+   * @returns The artifact attestation with digest and metadata.
+   * @throws {@link CryptoError} if signing fails.
+   *
+   * @example
+   * ```typescript
+   * const result = auths.artifacts.signBytes({
+   *   data: Buffer.from('binary content'),
+   *   identityDid: identity.did,
+   * })
+   * ```
+   */
+  signBytes(opts: SignArtifactBytesOptions): ArtifactResult {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      return native.signArtifactBytes(
+        opts.data,
+        opts.identityDid,
+        this.client.repoPath,
+        pp,
+        opts.expiresInDays ?? null,
+        opts.note ?? null,
+      )
+    } catch (err) {
+      throw mapNativeError(err, CryptoError)
+    }
+  }
+}

package/lib/attestations.ts

@@ -0,0 +1,126 @@
+import native from './native'
+import { mapNativeError, StorageError } from './errors'
+import type { Auths } from './client'
+
+/** An attestation record from the local registry. */
+export interface AttestationInfo {
+  /** Unique resource identifier of the attestation. */
+  rid: string
+  /** DID of the issuer (identity that signed the attestation). */
+  issuer: string
+  /** DID of the subject (device or agent being attested). */
+  subject: string
+  /** DID of the device this attestation applies to. */
+  deviceDid: string
+  /** List of capabilities granted (e.g. `['sign']`). */
+  capabilities: string[]
+  /** Signer type: `'human'`, `'agent'`, or `'workload'`, or `null`. */
+  signerType: string | null
+  /** Expiration timestamp (RFC 3339), or `null` if no expiry. */
+  expiresAt: string | null
+  /** Revocation timestamp (RFC 3339), or `null` if not revoked. */
+  revokedAt: string | null
+  /** Creation timestamp (RFC 3339), or `null`. */
+  createdAt: string | null
+  /** DID of the identity that delegated this attestation, or `null`. */
+  delegatedBy: string | null
+  /** Raw JSON-serialized attestation. */
+  json: string
+}
+
+/**
+ * Queries attestations stored in the local registry.
+ *
+ * Access via {@link Auths.attestations}.
+ *
+ * @example
+ * ```typescript
+ * const atts = auths.attestations.list()
+ * const latest = auths.attestations.getLatest(device.did)
+ * ```
+ */
+export class AttestationService {
+  constructor(private client: Auths) {}
+
+  /**
+   * Lists all attestations in the local registry.
+   *
+   * @returns Array of attestation records.
+   * @throws {@link StorageError} if the operation fails.
+   */
+  list(): AttestationInfo[] {
+    try {
+      return native.listAttestations(this.client.repoPath).map(a => ({
+        rid: a.rid,
+        issuer: a.issuer,
+        subject: a.subject,
+        deviceDid: a.deviceDid,
+        capabilities: a.capabilities,
+        signerType: a.signerType ?? null,
+        expiresAt: a.expiresAt ?? null,
+        revokedAt: a.revokedAt ?? null,
+        createdAt: a.createdAt ?? null,
+        delegatedBy: a.delegatedBy ?? null,
+        json: a.json,
+      }))
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+
+  /**
+   * Lists attestations for a specific device.
+   *
+   * @param deviceDid - DID of the device to filter by.
+   * @returns Array of attestation records for the device.
+   * @throws {@link StorageError} if the operation fails.
+   */
+  listByDevice(deviceDid: string): AttestationInfo[] {
+    try {
+      return native.listAttestationsByDevice(this.client.repoPath, deviceDid).map(a => ({
+        rid: a.rid,
+        issuer: a.issuer,
+        subject: a.subject,
+        deviceDid: a.deviceDid,
+        capabilities: a.capabilities,
+        signerType: a.signerType ?? null,
+        expiresAt: a.expiresAt ?? null,
+        revokedAt: a.revokedAt ?? null,
+        createdAt: a.createdAt ?? null,
+        delegatedBy: a.delegatedBy ?? null,
+        json: a.json,
+      }))
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+
+  /**
+   * Retrieves the latest attestation for a device.
+   *
+   * @param deviceDid - DID of the device.
+   * @returns The latest attestation, or `null` if none found.
+   * @throws {@link StorageError} if the operation fails.
+   */
+  getLatest(deviceDid: string): AttestationInfo | null {
+    try {
+      const a = native.getLatestAttestation(this.client.repoPath, deviceDid)
+      if (!a) return null
+      return {
+        rid: a.rid,
+        issuer: a.issuer,
+        subject: a.subject,
+        deviceDid: a.deviceDid,
+        capabilities: a.capabilities,
+        signerType: a.signerType ?? null,
+        expiresAt: a.expiresAt ?? null,
+        revokedAt: a.revokedAt ?? null,
+        createdAt: a.createdAt ?? null,
+        delegatedBy: a.delegatedBy ?? null,
+        json: a.json,
+      }
+    } catch (err) {
+      throw mapNativeError(err, StorageError)
+    }
+  }
+}

package/lib/audit.ts

@@ -0,0 +1,189 @@
+import { readFileSync } from 'node:fs'
+import native from './native'
+import { mapNativeError, VerificationError } from './errors'
+import type { Auths } from './client'
+
+/** Full audit report for a Git repository's commit signatures. */
+export interface AuditReport {
+  /** Individual commit audit entries. */
+  commits: AuditCommit[]
+  /** Aggregate signature statistics. */
+  summary: AuditSummary
+}
+
+/** Audit information for a single Git commit. */
+export interface AuditCommit {
+  /** Git object ID (SHA). */
+  oid: string
+  /** Commit author name. */
+  author_name: string
+  /** Commit author email. */
+  author_email: string
+  /** Commit date (ISO 8601). */
+  date: string
+  /** Commit message (first line). */
+  message: string
+  /** Signature type (`'auths'`, `'gpg'`, `'ssh'`), or `null` if unsigned. */
+  signature_type: string | null
+  /** DID of the signer, or `null` if not an Auths signature. */
+  signer_did: string | null
+  /** Whether the signature verified successfully, or `null` if unsigned. */
+  verified: boolean | null
+}
+
+/** Aggregate statistics from an audit report. */
+export interface AuditSummary {
+  /** Total number of commits analyzed. */
+  total_commits: number
+  /** Number of signed commits (any method). */
+  signed_commits: number
+  /** Number of unsigned commits. */
+  unsigned_commits: number
+  /** Number of Auths-signed commits. */
+  auths_signed: number
+  /** Number of GPG-signed commits. */
+  gpg_signed: number
+  /** Number of SSH-signed commits. */
+  ssh_signed: number
+  /** Number of signatures that passed verification. */
+  verification_passed: number
+  /** Number of signatures that failed verification. */
+  verification_failed: number
+}
+
+/** Options for {@link AuditService.report}. */
+export interface AuditReportOptions {
+  /** Path to the Git repository to audit. */
+  targetRepoPath: string
+  /** Only include commits after this date (ISO 8601). */
+  since?: string
+  /** Only include commits before this date (ISO 8601). */
+  until?: string
+  /** Only include commits by this author. */
+  author?: string
+  /** Maximum number of commits to analyze. */
+  limit?: number
+  /** Path to an Auths identity-bundle JSON file for signer DID resolution. */
+  identityBundlePath?: string
+}
+
+/** Parsed identity bundle metadata. */
+export interface IdentityBundleInfo {
+  /** Identity DID (`did:keri:...`). */
+  did: string
+  /** Hex-encoded Ed25519 public key. */
+  publicKeyHex: string
+  /** Human-readable identity label. */
+  label: string | null
+  /** Number of device attestations in the chain. */
+  deviceCount: number
+}
+
+/**
+ * Parse an Auths identity-bundle JSON file.
+ *
+ * @param path - Path to the identity-bundle JSON file.
+ * @returns The parsed bundle object.
+ *
+ * @example
+ * ```typescript
+ * const bundle = parseIdentityBundle('.auths/identity-bundle.json')
+ * console.log(bundle.did)
+ * ```
+ */
+export function parseIdentityBundle(path: string): Record<string, unknown> {
+  const content = readFileSync(path, 'utf-8')
+  return JSON.parse(content) as Record<string, unknown>
+}
+
+/**
+ * Parse an identity bundle into a typed {@link IdentityBundleInfo}.
+ *
+ * @param path - Path to the identity-bundle JSON file.
+ * @returns Typed bundle metadata.
+ */
+export function parseIdentityBundleInfo(path: string): IdentityBundleInfo {
+  const bundle = parseIdentityBundle(path)
+  const pkHex = (bundle.public_key_hex ?? bundle.publicKeyHex ?? '') as string
+  const chain = (bundle.attestation_chain ?? []) as unknown[]
+  return {
+    did: (bundle.did ?? '') as string,
+    publicKeyHex: pkHex,
+    label: (bundle.label ?? null) as string | null,
+    deviceCount: chain.length,
+  }
+}
+
+/** Options for {@link AuditService.isCompliant}. */
+export interface AuditComplianceOptions {
+  /** Path to the Git repository to audit. */
+  targetRepoPath: string
+  /** Only include commits after this date (ISO 8601). */
+  since?: string
+  /** Only include commits before this date (ISO 8601). */
+  until?: string
+  /** Only include commits by this author. */
+  author?: string
+}
+
+/**
+ * Audits Git repositories for commit signature compliance.
+ *
+ * Access via {@link Auths.audit}.
+ *
+ * @example
+ * ```typescript
+ * const report = auths.audit.report({ targetRepoPath: '/path/to/repo' })
+ * console.log(report.summary.unsigned_commits)
+ * ```
+ */
+export class AuditService {
+  constructor(private client: Auths) {}
+
+  /**
+   * Generates an audit report for a Git repository's commit signatures.
+   *
+   * @param opts - Audit options.
+   * @returns The audit report with per-commit details and summary statistics.
+   * @throws {@link VerificationError} if the audit fails.
+   *
+   * @example
+   * ```typescript
+   * const report = auths.audit.report({ targetRepoPath: '/path/to/repo' })
+   * console.log(report.summary.total_commits)
+   * ```
+   */
+  report(opts: AuditReportOptions): AuditReport {
+    try {
+      const json = native.generateAuditReport(
+        opts.targetRepoPath,
+        this.client.repoPath,
+        opts.since ?? null,
+        opts.until ?? null,
+        opts.author ?? null,
+        opts.limit ?? null,
+      )
+      return JSON.parse(json)
+    } catch (err) {
+      throw mapNativeError(err, VerificationError)
+    }
+  }
+
+  /**
+   * Checks whether all commits in a repository are signed.
+   *
+   * @param opts - Compliance check options.
+   * @returns `true` if every commit is signed, `false` otherwise.
+   *
+   * @example
+   * ```typescript
+   * if (auths.audit.isCompliant({ targetRepoPath: '/path/to/repo' })) {
+   *   console.log('All commits signed')
+   * }
+   * ```
+   */
+  isCompliant(opts: AuditComplianceOptions): boolean {
+    const report = this.report(opts)
+    return report.summary.unsigned_commits === 0
+  }
+}