@auths-dev/sdk 0.0.1 → 0.1.0

package/lib/native.ts

@@ -0,0 +1,255 @@
+// Type declarations for native napi-rs bindings (auto-generated at build time)
+// This file provides typed access to the Rust #[napi] functions
+
+export interface NapiVerificationResult {
+  valid: boolean
+  error?: string | null
+  errorCode?: string | null
+}
+
+export interface NapiVerificationStatus {
+  statusType: string
+  at?: string | null
+  step?: number | null
+  missingLink?: string | null
+  required?: number | null
+  verified?: number | null
+}
+
+export interface NapiChainLink {
+  issuer: string
+  subject: string
+  valid: boolean
+  error?: string | null
+}
+
+export interface NapiVerificationReport {
+  status: NapiVerificationStatus
+  chain: NapiChainLink[]
+  warnings: string[]
+}
+
+export interface NapiIdentityResult {
+  did: string
+  keyAlias: string
+  publicKeyHex: string
+}
+
+export interface NapiAgentIdentityBundle {
+  agentDid: string
+  keyAlias: string
+  attestationJson: string
+  publicKeyHex: string
+  repoPath?: string | null
+}
+
+export interface NapiDelegatedAgentBundle {
+  agentDid: string
+  keyAlias: string
+  attestationJson: string
+  publicKeyHex: string
+  repoPath?: string | null
+}
+
+export interface NapiRotationResult {
+  controllerDid: string
+  newKeyFingerprint: string
+  previousKeyFingerprint: string
+  sequence: number
+}
+
+export interface NapiLinkResult {
+  deviceDid: string
+  attestationId: string
+}
+
+export interface NapiExtensionResult {
+  deviceDid: string
+  newExpiresAt: string
+  previousExpiresAt?: string | null
+}
+
+export interface NapiCommitSignResult {
+  signature: string
+  signerDid: string
+}
+
+export interface NapiActionEnvelope {
+  envelopeJson: string
+  signatureHex: string
+  signerDid: string
+}
+
+export interface NapiCommitSignPemResult {
+  signaturePem: string
+  method: string
+  namespace: string
+}
+
+export interface NapiOrgResult {
+  orgPrefix: string
+  orgDid: string
+  label: string
+  repoPath: string
+}
+
+export interface NapiOrgMember {
+  memberDid: string
+  role: string
+  capabilitiesJson: string
+  issuerDid: string
+  attestationRid: string
+  revoked: boolean
+  expiresAt?: string | null
+}
+
+export interface NapiAttestation {
+  rid: string
+  issuer: string
+  subject: string
+  deviceDid: string
+  capabilities: string[]
+  signerType?: string | null
+  expiresAt?: string | null
+  revokedAt?: string | null
+  createdAt?: string | null
+  delegatedBy?: string | null
+  json: string
+}
+
+export interface NapiPinnedIdentity {
+  did: string
+  label?: string | null
+  trustLevel: string
+  firstSeen: string
+  kelSequence?: number | null
+  pinnedAt: string
+}
+
+export interface NapiWitnessResult {
+  url: string
+  did?: string | null
+  label?: string | null
+}
+
+export interface NapiArtifactResult {
+  attestationJson: string
+  rid: string
+  digest: string
+  fileSize: number
+}
+
+export interface NapiPolicyDecision {
+  outcome: string
+  reason: string
+  message: string
+}
+
+export interface NapiPairingSession {
+  sessionId: string
+  shortCode: string
+  endpoint: string
+  token: string
+  controllerDid: string
+}
+
+export interface NapiPairingResponse {
+  deviceDid: string
+  deviceName?: string | null
+  devicePublicKeyHex: string
+}
+
+export interface NapiPairingResult {
+  deviceDid: string
+  deviceName?: string | null
+  attestationRid: string
+}
+
+export interface NapiPairingHandleInstance {
+  session: NapiPairingSession
+  waitForResponse(timeoutSecs?: number | null): Promise<NapiPairingResponse>
+  complete(deviceDid: string, devicePublicKeyHex: string, repoPath: string, capabilitiesJson?: string | null, passphrase?: string | null): Promise<NapiPairingResult>
+  stop(): Promise<void>
+}
+
+export interface NativeBindings {
+  version(): string
+
+  // Identity
+  createIdentity(keyAlias: string, repoPath: string, passphrase?: string | null): NapiIdentityResult
+  createAgentIdentity(agentName: string, capabilities: string[], repoPath: string, passphrase?: string | null): NapiAgentIdentityBundle
+  delegateAgent(agentName: string, capabilities: string[], parentRepoPath: string, passphrase?: string | null, expiresInDays?: number | null, identityDid?: string | null): NapiDelegatedAgentBundle
+  rotateIdentityKeys(repoPath: string, identityKeyAlias?: string | null, nextKeyAlias?: string | null, passphrase?: string | null): NapiRotationResult
+  getIdentityPublicKey(identityDid: string, repoPath: string, passphrase?: string | null): string
+
+  // Device
+  linkDeviceToIdentity(identityKeyAlias: string, capabilities: string[], repoPath: string, passphrase?: string | null, expiresInDays?: number | null): NapiLinkResult
+  revokeDeviceFromIdentity(deviceDid: string, identityKeyAlias: string, repoPath: string, passphrase?: string | null, note?: string | null): void
+  extendDeviceAuthorization(deviceDid: string, identityKeyAlias: string, days: number, repoPath: string, passphrase?: string | null): NapiExtensionResult
+
+  // Signing
+  signAsIdentity(message: Buffer, identityDid: string, repoPath: string, passphrase?: string | null): NapiCommitSignResult
+  signActionAsIdentity(actionType: string, payloadJson: string, identityDid: string, repoPath: string, passphrase?: string | null): NapiActionEnvelope
+  signAsAgent(message: Buffer, keyAlias: string, repoPath: string, passphrase?: string | null): NapiCommitSignResult
+  signActionAsAgent(actionType: string, payloadJson: string, keyAlias: string, agentDid: string, repoPath: string, passphrase?: string | null): NapiActionEnvelope
+
+  // Commit signing
+  signCommit(data: Buffer, identityKeyAlias: string, repoPath: string, passphrase?: string | null): NapiCommitSignPemResult
+
+  // Org
+  createOrg(label: string, repoPath: string, passphrase?: string | null): NapiOrgResult
+  addOrgMember(orgDid: string, memberDid: string, role: string, repoPath: string, capabilitiesJson?: string | null, passphrase?: string | null, note?: string | null, memberPublicKeyHex?: string | null): NapiOrgMember
+  revokeOrgMember(orgDid: string, memberDid: string, repoPath: string, passphrase?: string | null, note?: string | null, memberPublicKeyHex?: string | null): NapiOrgMember
+  listOrgMembers(orgDid: string, includeRevoked: boolean, repoPath: string): string
+
+  // Attestation query
+  listAttestations(repoPath: string): NapiAttestation[]
+  listAttestationsByDevice(repoPath: string, deviceDid: string): NapiAttestation[]
+  getLatestAttestation(repoPath: string, deviceDid: string): NapiAttestation | null
+
+  // Trust
+  pinIdentity(did: string, repoPath: string, label?: string | null, trustLevel?: string | null): NapiPinnedIdentity
+  removePinnedIdentity(did: string, repoPath: string): void
+  listPinnedIdentities(repoPath: string): string
+  getPinnedIdentity(did: string, repoPath: string): NapiPinnedIdentity | null
+
+  // Witness
+  addWitness(urlStr: string, repoPath: string, label?: string | null): NapiWitnessResult
+  removeWitness(urlStr: string, repoPath: string): void
+  listWitnesses(repoPath: string): string
+
+  // Artifact
+  signArtifact(filePath: string, identityKeyAlias: string, repoPath: string, passphrase?: string | null, expiresInDays?: number | null, note?: string | null): NapiArtifactResult
+  signArtifactBytes(data: Buffer, identityKeyAlias: string, repoPath: string, passphrase?: string | null, expiresInDays?: number | null, note?: string | null): NapiArtifactResult
+
+  // Audit
+  generateAuditReport(targetRepoPath: string, authsRepoPath: string, since?: string | null, until?: string | null, author?: string | null, limit?: number | null): string
+
+  // Diagnostics
+  runDiagnostics(repoPath: string, passphrase?: string | null): string
+
+  // Policy
+  compilePolicy(policyJson: string): string
+  evaluatePolicy(compiledPolicyJson: string, issuer: string, subject: string, capabilities?: string[] | null, role?: string | null, revoked?: boolean | null, expiresAt?: string | null, repo?: string | null, environment?: string | null, signerType?: string | null, delegatedBy?: string | null, chainDepth?: number | null): NapiPolicyDecision
+
+  // Pairing
+  NapiPairingHandle: {
+    createSession(repoPath: string, capabilitiesJson?: string | null, timeoutSecs?: number | null, bindAddress?: string | null, enableMdns?: boolean | null, passphrase?: string | null): Promise<NapiPairingHandleInstance>
+  }
+  joinPairingSession(shortCode: string, endpoint: string, token: string, repoPath: string, deviceName?: string | null, passphrase?: string | null): Promise<NapiPairingResponse>
+
+  // Verification
+  verifyAttestation(attestationJson: string, issuerPkHex: string): Promise<NapiVerificationResult>
+  verifyChain(attestationsJson: string[], rootPkHex: string): Promise<NapiVerificationReport>
+  verifyDeviceAuthorization(identityDid: string, deviceDid: string, attestationsJson: string[], identityPkHex: string): Promise<NapiVerificationReport>
+  verifyAttestationWithCapability(attestationJson: string, issuerPkHex: string, requiredCapability: string): Promise<NapiVerificationResult>
+  verifyChainWithCapability(attestationsJson: string[], rootPkHex: string, requiredCapability: string): Promise<NapiVerificationReport>
+  verifyAtTime(attestationJson: string, issuerPkHex: string, atRfc3339: string): Promise<NapiVerificationResult>
+  verifyAtTimeWithCapability(attestationJson: string, issuerPkHex: string, atRfc3339: string, requiredCapability: string): Promise<NapiVerificationResult>
+  verifyChainWithWitnesses(attestationsJson: string[], rootPkHex: string, receiptsJson: string[], witnessKeysJson: string[], threshold: number): Promise<NapiVerificationReport>
+}
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const native: NativeBindings = require('../index.js')
+
+export default native

package/lib/org.ts

@@ -0,0 +1,235 @@
+import native from './native'
+import { mapNativeError, OrgError } from './errors'
+import type { Auths } from './client'
+
+/** Result of creating an organization. */
+export interface OrgResult {
+  /** Internal prefix for the organization. */
+  orgPrefix: string
+  /** The organization's KERI DID. */
+  orgDid: string
+  /** Human-readable label. */
+  label: string
+  /** Path to the registry storing the organization. */
+  repoPath: string
+}
+
+/** An organization member record. */
+export interface OrgMember {
+  /** DID of the member. */
+  memberDid: string
+  /** Role within the organization (e.g. `'admin'`, `'member'`). */
+  role: string
+  /** Capabilities granted to this member. */
+  capabilities: string[]
+  /** DID of the admin who added this member. */
+  issuerDid: string
+  /** Resource identifier of the membership attestation. */
+  attestationRid: string
+  /** Whether the membership has been revoked. */
+  revoked: boolean
+  /** Expiration timestamp (RFC 3339), or `null` if no expiry. */
+  expiresAt: string | null
+}
+
+/**
+ * Check whether an organization member has admin role.
+ *
+ * @param member - The organization member to check.
+ * @returns `true` if the member's role is `'admin'`.
+ */
+export function isAdmin(member: OrgMember): boolean {
+  return member.role === 'admin'
+}
+
+/** Options for {@link OrgService.create}. */
+export interface CreateOrgOptions {
+  /** Human-readable label for the organization. */
+  label: string
+  /** Override the client's repo path. */
+  repoPath?: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+}
+
+/** Options for {@link OrgService.addMember}. */
+export interface AddOrgMemberOptions {
+  /** DID of the organization. */
+  orgDid: string
+  /** DID of the member to add. */
+  memberDid: string
+  /** Role to assign (e.g. `'admin'`, `'member'`). */
+  role: string
+  /** Capabilities to grant the member. */
+  capabilities?: string[]
+  /** Override the client's passphrase. */
+  passphrase?: string
+  /** Optional note for the membership record. */
+  note?: string
+  /** Hex-encoded public key of the member (required for cross-repo adds). */
+  memberPublicKeyHex?: string
+}
+
+/** Options for {@link OrgService.revokeMember}. */
+export interface RevokeOrgMemberOptions {
+  /** DID of the organization. */
+  orgDid: string
+  /** DID of the member to revoke. */
+  memberDid: string
+  /** Override the client's passphrase. */
+  passphrase?: string
+  /** Optional revocation note. */
+  note?: string
+  /** Hex-encoded public key of the member. */
+  memberPublicKeyHex?: string
+}
+
+/** Options for {@link OrgService.listMembers}. */
+export interface ListOrgMembersOptions {
+  /** DID of the organization. */
+  orgDid: string
+  /** Whether to include revoked members. Defaults to `false`. */
+  includeRevoked?: boolean
+}
+
+/**
+ * Manages organizations and their membership.
+ *
+ * Access via {@link Auths.orgs}.
+ *
+ * @example
+ * ```typescript
+ * const org = auths.orgs.create({ label: 'my-team' })
+ * auths.orgs.addMember({
+ *   orgDid: org.orgDid,
+ *   memberDid: dev.did,
+ *   role: 'member',
+ *   memberPublicKeyHex: dev.publicKey,
+ * })
+ * ```
+ */
+export class OrgService {
+  constructor(private client: Auths) {}
+
+  /**
+   * Creates a new organization.
+   *
+   * @param opts - Organization options.
+   * @returns The created organization.
+   * @throws {@link OrgError} if creation fails.
+   *
+   * @example
+   * ```typescript
+   * const org = auths.orgs.create({ label: 'engineering' })
+   * console.log(org.orgDid) // did:keri:...
+   * ```
+   */
+  create(opts: CreateOrgOptions): OrgResult {
+    const rp = opts.repoPath ?? this.client.repoPath
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      return native.createOrg(opts.label, rp, pp)
+    } catch (err) {
+      throw mapNativeError(err, OrgError)
+    }
+  }
+
+  /**
+   * Adds a member to an organization.
+   *
+   * @param opts - Member options.
+   * @returns The new member record.
+   * @throws {@link OrgError} if the operation fails.
+   *
+   * @example
+   * ```typescript
+   * const member = auths.orgs.addMember({
+   *   orgDid: org.orgDid,
+   *   memberDid: dev.did,
+   *   role: 'member',
+   *   memberPublicKeyHex: dev.publicKey,
+   * })
+   * ```
+   */
+  addMember(opts: AddOrgMemberOptions): OrgMember {
+    const pp = opts.passphrase ?? this.client.passphrase
+    const capsJson = opts.capabilities ? JSON.stringify(opts.capabilities) : null
+    try {
+      const result = native.addOrgMember(
+        opts.orgDid,
+        opts.memberDid,
+        opts.role,
+        this.client.repoPath,
+        capsJson,
+        pp,
+        opts.note ?? null,
+        opts.memberPublicKeyHex ?? null,
+      )
+      return {
+        memberDid: result.memberDid,
+        role: result.role,
+        capabilities: JSON.parse(result.capabilitiesJson || '[]'),
+        issuerDid: result.issuerDid,
+        attestationRid: result.attestationRid,
+        revoked: result.revoked,
+        expiresAt: result.expiresAt ?? null,
+      }
+    } catch (err) {
+      throw mapNativeError(err, OrgError)
+    }
+  }
+
+  /**
+   * Revokes a member's access to an organization.
+   *
+   * @param opts - Revocation options.
+   * @returns The updated member record with `revoked: true`.
+   * @throws {@link OrgError} if the operation fails.
+   */
+  revokeMember(opts: RevokeOrgMemberOptions): OrgMember {
+    const pp = opts.passphrase ?? this.client.passphrase
+    try {
+      const result = native.revokeOrgMember(
+        opts.orgDid,
+        opts.memberDid,
+        this.client.repoPath,
+        pp,
+        opts.note ?? null,
+        opts.memberPublicKeyHex ?? null,
+      )
+      return {
+        memberDid: result.memberDid,
+        role: result.role,
+        capabilities: JSON.parse(result.capabilitiesJson || '[]'),
+        issuerDid: result.issuerDid,
+        attestationRid: result.attestationRid,
+        revoked: result.revoked,
+        expiresAt: result.expiresAt ?? null,
+      }
+    } catch (err) {
+      throw mapNativeError(err, OrgError)
+    }
+  }
+
+  /**
+   * Lists members of an organization.
+   *
+   * @param opts - List options.
+   * @returns Array of member records.
+   * @throws {@link OrgError} if the operation fails.
+   *
+   * @example
+   * ```typescript
+   * const members = auths.orgs.listMembers({ orgDid: org.orgDid })
+   * console.log(members.length)
+   * ```
+   */
+  listMembers(opts: ListOrgMembersOptions): OrgMember[] {
+    try {
+      const json = native.listOrgMembers(opts.orgDid, opts.includeRevoked ?? false, this.client.repoPath)
+      return JSON.parse(json)
+    } catch (err) {
+      throw mapNativeError(err, OrgError)
+    }
+  }
+}