feat: embedded key resolution (#168)

* feat: draft did:dns support

* fix: type errors

* fix: test coverage

* feat: generalize DID principal

* chore: remove obsolete code

* chore: export from / parse functions

* chore: stub the test

* feat: embedded key resolution

* fix: type errors

* chore: remove redundant code

* fix: remaining issues

* fix: failing test

* chore: enable assertion

* fix: naming not to confuse with did resolution

* chore: describe `authority` field

* chore: remove obsolete assert

* chore: add jsdoc comments

packages/interface/src/capability.ts

@@ -5,12 +5,16 @@ import {
   Result,
   Failure,
   PrincipalParser,
+  PrincipalResolver,
   Signer,
   URI,
   UCANLink,
   Await,
   IssuedInvocationView,
   UCANOptions,
+  DIDKey,
+  Verifier,
+  API,
 } from './lib.js'
 
 export interface Source {
@@ -358,18 +362,40 @@ export interface ProofResolver extends PrincipalOptions {
   /**
    * You can provide a proof resolver that validator will call when UCAN
    * links to external proof. If resolver is not provided validator may not
-   * be able to explore correesponding path within a proof chain.
+   * be able to explore corresponding path within a proof chain.
    */
   resolve?: (proof: Link) => Await<Result<Delegation, UnavailableProof>>
 }
 
-export interface ValidationOptions<C extends ParsedCapability>
-  extends Partial<CanIssue>,
+export interface Validator {
+  /**
+   * Validator must be provided a `Verifier` corresponding to local authority.
+   * Capability provider service will use one corresponding to own DID or it's
+   * supervisor's DID if it acts under it's authority.
+   *
+   * This allows service identified by non did:key e.g. did:web or did:dns to
+   * pass resolved key so it does not need to be resolved at runtime.
+   */
+  authority: Verifier
+}
+
+export interface ValidationOptions<
+  C extends ParsedCapability = ParsedCapability
+> extends Partial<CanIssue>,
+    Validator,
     PrincipalOptions,
+    PrincipalResolver,
     ProofResolver {
   capability: CapabilityParser<Match<C, any>>
 }
 
+export interface ClaimOptions
+  extends Partial<CanIssue>,
+    Validator,
+    PrincipalOptions,
+    PrincipalResolver,
+    ProofResolver {}
+
 export interface DelegationError extends Failure {
   name: 'InvalidClaim'
   causes: (InvalidCapability | EscalatedDelegation | DelegationError)[]
@@ -405,6 +431,13 @@ export interface UnavailableProof extends Failure {
   readonly link: UCANLink
 }
 
+export interface DIDKeyResolutionError extends Failure {
+  readonly name: 'DIDKeyResolutionError'
+  readonly did: UCAN.DID
+
+  readonly cause?: Unauthorized
+}
+
 export interface Expired extends Failure {
   readonly name: 'Expired'
   readonly delegation: Delegation
@@ -432,16 +465,21 @@ export type InvalidProof =
   | NotValidBefore
   | InvalidSignature
   | InvalidAudience
+  | DIDKeyResolutionError
+  | UnavailableProof
 
 export interface Unauthorized extends Failure {
   name: 'Unauthorized'
-  cause: InvalidCapability | InvalidProof | InvalidClaim
+
+  delegationErrors: DelegationError[]
+  unknownCapabilities: Capability[]
+  invalidProofs: InvalidProof[]
+  failedProofs: InvalidClaim[]
 }
 
 export interface InvalidClaim extends Failure {
   issuer: UCAN.Principal
   name: 'InvalidClaim'
-  capability: ParsedCapability
   delegation: Delegation
 
   message: string

packages/interface/src/lib.ts

@@ -26,6 +26,7 @@ import {
   InvalidAudience,
   Unauthorized,
   UnavailableProof,
+  DIDKeyResolutionError,
   ParsedCapability,
   CapabilityParser,
 } from './capability.js'
@@ -239,7 +240,7 @@ export type InvocationError =
   | Unauthorized
 
 export interface InvocationContext extends CanIssue {
-  id: Principal
+  id: Verifier
   my?: (issuer: DID) => Capability[]
   resolve?: (proof: UCANLink) => Await<Result<Delegation, UnavailableProof>>
 
@@ -425,7 +426,7 @@ export interface ServerOptions
    * Service DID which will be used to verify that received invocation
    * audience matches it.
    */
-  readonly id: Principal
+  readonly id: Verifier
 }
 
 /**
@@ -491,6 +492,10 @@ export type URI<P extends Protocol = Protocol> = `${P}${string}` &
     protocol: P
   }>
 
+export interface ComposedDIDParser extends PrincipalParser {
+  or(parser: PrincipalParser): ComposedDIDParser
+}
+
 /**
  * A `PrincipalParser` provides {@link Verifier} instances that can validate UCANs issued
  * by a given {@link Principal}.
@@ -499,6 +504,17 @@ export interface PrincipalParser {
   parse(did: UCAN.DID): Verifier
 }
 
+/**
+ * A `PrincipalResolver` is used to resolve a key of the principal that is
+ * identified by DID different from did:key method. It can be passed into a
+ * UCAN validator in order to augmented it with additional DID methods support.
+ */
+export interface PrincipalResolver {
+  resolveDIDKey?: (
+    did: UCAN.DID
+  ) => Await<Result<DIDKey, DIDKeyResolutionError>>
+}
+
 /**
  * Represents component that can create a signer from it's archive. Usually
  * signer module would provide `from` function and therefor be an implementation
@@ -517,6 +533,23 @@ export interface SignerImporter<
   from(archive: SignerArchive<ID, Alg>): Signer<ID, Alg>
 }
 
+export interface CompositeImporter<
+  Variants extends [SignerImporter, ...SignerImporter[]]
+> {
+  from: Intersection<Variants[number]['from']>
+  or<Other extends SignerImporter>(
+    other: Other
+  ): CompositeImporter<[Other, ...Variants]>
+}
+
+export interface Importer<Self extends Signer = Signer> {
+  from(archive: Archive<Self>): Self
+}
+
+export interface Archive<Self extends Signer> {
+  id: ReturnType<Signer['did']>
+  keys: { [Key: DIDKey]: KeyArchive<Signer['signatureCode']> }
+}
 /**
  * Principal that can issue UCANs (and sign payloads). While it's primary role
  * is to sign payloads it also extends `Verifier` interface so it could be used
@@ -598,6 +631,10 @@ export interface Signer<ID extends DID = DID, Alg extends SigAlg = SigAlg>
  */
 export interface Verifier<ID extends DID = DID, Alg extends SigAlg = SigAlg>
   extends UCAN.Verifier<ID, Alg> {
+  /**
+   * Returns unwrapped did:key of this principal.
+   */
+  toDIDKey(): DIDKey
   /**
    * Wraps key of this verifier into a verifier with a different DID. This is
    * primarily used to wrap {@link VerifierKey} into a {@link Verifier} that has