@ucanto/interface - npm Package Compare versions

Comparing version 4.0.2 to 4.0.3

dist/src/capability.d.ts

 import { Ability, Capability, DID, Link, Resource } from '@ipld/dag-ucan';
 import * as UCAN from '@ipld/dag-ucan';
-import { Delegation, Result, Failure, PrincipalParser, Signer, URI, UCANLink, Await, IssuedInvocationView, UCANOptions } from './lib.js';
+import { Delegation, Result, Failure, PrincipalParser, PrincipalResolver, Signer, URI, UCANLink, Await, IssuedInvocationView, UCANOptions, Verifier } from './lib.js';
 export interface Source {
@@ -259,9 +259,22 @@ capability: Capability;
      * 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>, PrincipalOptions, ProofResolver {
+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 {
@@ -295,2 +308,7 @@ name: 'InvalidClaim';
 }
+export interface DIDKeyResolutionError extends Failure {
+    readonly name: 'DIDKeyResolutionError';
+    readonly did: UCAN.DID;
+    readonly cause?: Unauthorized;
+}
 export interface Expired extends Failure {
@@ -315,6 +333,9 @@ readonly name: 'Expired';
  */
-export declare type InvalidProof = Expired | NotValidBefore | InvalidSignature | InvalidAudience;
+export declare type InvalidProof = Expired | NotValidBefore | InvalidSignature | InvalidAudience | DIDKeyResolutionError | UnavailableProof;
 export interface Unauthorized extends Failure {
     name: 'Unauthorized';
-    cause: InvalidCapability | InvalidProof | InvalidClaim;
+    delegationErrors: DelegationError[];
+    unknownCapabilities: Capability[];
+    invalidProofs: InvalidProof[];
+    failedProofs: InvalidClaim[];
 }
@@ -324,3 +345,2 @@ export interface InvalidClaim extends Failure {
     name: 'InvalidClaim';
-    capability: ParsedCapability;
     delegation: Delegation;
@@ -327,0 +347,0 @@ message: string;

dist/src/lib.d.ts

 import { Ability, Block as UCANBlock, ByteView, Capabilities, Capability, DID, Fact, Link as UCANLink, MultihashHasher, MultihashDigest, MultibaseDecoder, MultibaseEncoder, Phantom, Resource, Signature, Principal, MulticodecCode, SigAlg } from '@ipld/dag-ucan';
 import { Link, Block as IPLDBlock } from 'multiformats';
 import * as UCAN from '@ipld/dag-ucan';
-import { CanIssue, Match, InvalidAudience, Unauthorized, UnavailableProof, ParsedCapability, CapabilityParser } from './capability.js';
+import { CanIssue, Match, InvalidAudience, Unauthorized, UnavailableProof, DIDKeyResolutionError, ParsedCapability, CapabilityParser } from './capability.js';
 import type * as Transport from './transport.js';
@@ -142,3 +142,3 @@ import type { Tuple, Block } from './transport.js';
 export interface InvocationContext extends CanIssue {
-    id: Principal;
+    id: Verifier;
     my?: (issuer: DID) => Capability[];
@@ -240,3 +240,3 @@ resolve?: (proof: UCANLink) => Await<Result<Delegation, UnavailableProof>>;
      */
-    readonly id: Principal;
+    readonly id: Verifier;
 }
@@ -291,2 +291,5 @@ /**
 }>;
+export interface ComposedDIDParser extends PrincipalParser {
+    or(parser: PrincipalParser): ComposedDIDParser;
+}
 /**
@@ -300,2 +303,10 @@ * A `PrincipalParser` provides {@link Verifier} instances that can validate UCANs issued
 /**
+ * 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
@@ -314,2 +325,15 @@ * signer module would provide `from` function and therefor be an implementation
 }
+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']>;
+    };
+}
 /**
@@ -390,2 +414,6 @@ * Principal that can issue UCANs (and sign payloads). While it's primary role
     /**
+     * Returns unwrapped did:key of this principal.
+     */
+    toDIDKey(): DIDKey;
+    /**
      * Wraps key of this verifier into a verifier with a different DID. This is
@@ -392,0 +420,0 @@ * primarily used to wrap {@link VerifierKey} into a {@link Verifier} that has

package.json

 {
   "name": "@ucanto/interface",
   "description": "interface definitions for ucanto",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "types": "./dist/src/lib.d.ts",
@@ -6,0 +6,0 @@ "main": "./src/lib.js",

src/capability.ts

@@ -8,2 +8,3 @@ import { Ability, Capability, DID, Link, Resource } from '@ipld/dag-ucan'
   PrincipalParser,
+  PrincipalResolver,
   Signer,
@@ -15,2 +16,5 @@ URI,
   UCANOptions,
+  DIDKey,
+  Verifier,
+  API,
 } from './lib.js'
@@ -363,3 +367,3 @@
    * 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.
    */
@@ -369,5 +373,20 @@ 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 {
@@ -377,2 +396,9 @@ capability: CapabilityParser<Match<C, any>>
 
+export interface ClaimOptions
+  extends Partial<CanIssue>,
+    Validator,
+    PrincipalOptions,
+    PrincipalResolver,
+    ProofResolver {}
+
 export interface DelegationError extends Failure {
@@ -413,2 +439,9 @@ name: 'InvalidClaim'
 
+export interface DIDKeyResolutionError extends Failure {
+  readonly name: 'DIDKeyResolutionError'
+  readonly did: UCAN.DID
+
+  readonly cause?: Unauthorized
+}
+
 export interface Expired extends Failure {
@@ -441,6 +474,12 @@ readonly name: 'Expired'
   | InvalidAudience
+  | DIDKeyResolutionError
+  | UnavailableProof
 
 export interface Unauthorized extends Failure {
   name: 'Unauthorized'
-  cause: InvalidCapability | InvalidProof | InvalidClaim
+
+  delegationErrors: DelegationError[]
+  unknownCapabilities: Capability[]
+  invalidProofs: InvalidProof[]
+  failedProofs: InvalidClaim[]
 }
@@ -451,3 +490,2 @@
   name: 'InvalidClaim'
-  capability: ParsedCapability
   delegation: Delegation
@@ -454,0 +492,0 @@

src/lib.ts

@@ -29,2 +29,3 @@ import {
   UnavailableProof,
+  DIDKeyResolutionError,
   ParsedCapability,
@@ -243,3 +244,3 @@ CapabilityParser,
 export interface InvocationContext extends CanIssue {
-  id: Principal
+  id: Verifier
   my?: (issuer: DID) => Capability[]
@@ -430,3 +431,3 @@ resolve?: (proof: UCANLink) => Await<Result<Delegation, UnavailableProof>>
    */
-  readonly id: Principal
+  readonly id: Verifier
 }
@@ -497,2 +498,6 @@
 
+export interface ComposedDIDParser extends PrincipalParser {
+  or(parser: PrincipalParser): ComposedDIDParser
+}
+
 /**
@@ -507,2 +512,13 @@ * A `PrincipalParser` provides {@link Verifier} instances that can validate UCANs issued
 /**
+ * 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
@@ -525,2 +541,19 @@ * signer module would provide `from` function and therefor be an implementation
 
+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']> }
+}
 /**
@@ -608,2 +641,6 @@ * Principal that can issue UCANs (and sign payloads). While it's primary role
   /**
+   * Returns unwrapped did:key of this principal.
+   */
+  toDIDKey(): DIDKey
+  /**
    * Wraps key of this verifier into a verifier with a different DID. This is
@@ -610,0 +647,0 @@ * primarily used to wrap {@link VerifierKey} into a {@link Verifier} that has

No alert changes

Worsened metrics

Total package byte prevSize

109571

-6.01%

Number of package files

15

-28.57%

Lines of code

2205

-0.05%

No dependency changes