Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@ucanto/interface

Package Overview
Dependencies
Maintainers
3
Versions
33
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@ucanto/interface - npm Package Compare versions

Comparing version 1.0.0 to 2.0.0

80

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, SigningPrincipal, URI, Await, IssuedInvocationView, UCANOptions } from './lib.js';
import { Delegation, Result, Failure, PrincipalParser, Signer, URI, Await, IssuedInvocationView, UCANOptions } from './lib.js';
export interface Source {

@@ -34,8 +34,9 @@ capability: Capability;

}
export interface Decoder<I extends unknown, O extends unknown, X extends {
export interface Reader<O = unknown, I = unknown, X extends {
error: true;
} = Failure> {
decode: (input: I) => Result<O, X>;
read: (input: I) => Result<O, X>;
}
export interface Caveats extends Record<string, Decoder<unknown, unknown, Failure>> {
export interface Caveats {
[key: string]: Reader<any, unknown>;
}

@@ -98,12 +99,33 @@ export declare type MatchResult<M extends Match> = Result<M, InvalidCapability>;

readonly can: M['value']['can'];
create(input: InferCreateOptions<M['value']['with'], M['value']['caveats']>): Capability<M['value']['can'], M['value']['uri']['href']> & M['value']['caveats'];
invoke(options: InvokeCapabilityOptions<M['value']['with'], M['value']['caveats']>): IssuedInvocationView<Capability<M['value']['can'], M['value']['uri']['href']> & M['value']['caveats']>;
create(input: InferCreateOptions<M['value']['with'], M['value']['nb']>): M['value'];
/**
* Creates an invocation of this capability. Function throws exception if
* non-optional fields are omitted.
*/
invoke(options: InferInvokeOptions<M['value']['with'], M['value']['nb']>): IssuedInvocationView<M['value']>;
/**
* Creates a delegation of this capability. Please note that all the
* `nb` fields are optional in delegation and only provided ones will
* be validated.
*/
delegate(options: InferDelegationOptions<M['value']['with'], M['value']['nb']>): Promise<Delegation<[M['value']]>>;
}
export declare type InferCreateOptions<R extends Resource, C extends {}> = {
with: Resource;
caveats?: {};
} & Optionalize<{
export declare type InferCreateOptions<R extends Resource, C extends {} | undefined> = keyof C extends never ? {
with: R;
caveats: InferCaveatParams<C>;
}>;
nb?: never;
} : {
with: R;
nb: C;
};
export declare type InferInvokeOptions<R extends Resource, C extends {} | undefined> = UCANOptions & {
issuer: Signer;
} & InferCreateOptions<R, C>;
export declare type InferDelegationOptions<R extends Resource, C extends {} | undefined> = UCANOptions & {
issuer: Signer;
with: R;
nb?: Partial<InferCreateOptions<R, C>['nb']>;
};
export declare type EmptyObject = {
[key: string | number | symbol]: never;
};
declare type Optionalize<T> = InferRequried<T> & InferOptional<T>;

@@ -116,5 +138,2 @@ declare type InferOptional<T> = {

};
export declare type InvokeCapabilityOptions<R extends Resource, C extends {}> = UCANOptions & InferCreateOptions<R, C> & {
issuer: SigningPrincipal;
};
export interface CapabilityParser<M extends Match = Match> extends View<M> {

@@ -190,15 +209,18 @@ /**

export declare type InferMatch<Members extends unknown[]> = Members extends [] ? [] : Members extends [Match<unknown, infer M>, ...infer Rest] ? [M, ...InferMatch<Rest>] : never;
export interface ParsedCapability<Can extends Ability = Ability, Resource extends URI = URI, C extends object = {}> {
export declare type ParsedCapability<Can extends Ability = Ability, Resource extends URI = URI, C extends object = {}> = keyof C extends never ? {
can: Can;
with: Resource['href'];
uri: Resource;
caveats: C;
}
with: Resource;
nb?: C;
} : {
can: Can;
with: Resource;
nb: C;
};
export declare type InferCaveats<C> = Optionalize<{
[K in keyof C]: C[K] extends Decoder<unknown, infer T, infer _> ? T : never;
[K in keyof C]: C[K] extends Reader<infer T, unknown, infer _> ? T : never;
}>;
export interface Descriptor<A extends Ability, R extends URI, C extends Caveats> {
can: A;
with: Decoder<Resource, R, Failure>;
caveats?: C;
with: Reader<R, Resource, Failure>;
nb?: C;
derives?: Derives<ParsedCapability<A, R, InferCaveats<C>>, ParsedCapability<A, R, InferCaveats<C>>>;

@@ -218,12 +240,4 @@ }

}
export interface IssuingOptions {
export interface ProofResolver extends PrincipalOptions {
/**
* You can provide default set of capabilities per did, which is used to
* validate whether claim is satisfied by `{ with: my:*, can: "*" }`. If
* not provided resolves to `[]`.
*/
my?: (issuer: DID) => Capability[];
}
export interface ProofResolver extends PrincipalOptions, IssuingOptions {
/**
* You can provide a proof resolver that validator will call when UCAN

@@ -235,3 +249,3 @@ * links to external proof. If resolver is not provided validator may not

}
export interface ValidationOptions<C extends ParsedCapability> extends CanIssue, IssuingOptions, PrincipalOptions, ProofResolver {
export interface ValidationOptions<C extends ParsedCapability> extends Partial<CanIssue>, PrincipalOptions, ProofResolver {
capability: CapabilityParser<Match<C, any>>;

@@ -238,0 +252,0 @@ }

@@ -1,12 +0,10 @@

import { Ability, Block as UCANBlock, ByteView, Capabilities, Capability, DID, Fact, Link as UCANLink, IPLDLink as Link, MultihashHasher, MultihashDigest, Phantom, Resource, Signature } from '@ipld/dag-ucan';
import { Ability, Block as UCANBlock, ByteView, Capabilities, Capability, DID, Fact, Link as UCANLink, IPLDLink as Link, MultihashHasher, MultihashDigest, Phantom, Resource, Signature, Principal, Verifier, Signer as UCANSigner } from '@ipld/dag-ucan';
import * as UCAN from '@ipld/dag-ucan';
import type { Principal, PrincipalParser, SigningPrincipal } from './principal.js';
import { CanIssue, InvalidAudience, Unauthorized, UnavailableProof } from './capability.js';
import { CanIssue, Match, InvalidAudience, Unauthorized, UnavailableProof, ParsedCapability, CapabilityParser } from './capability.js';
import type * as Transport from './transport.js';
import type { Tuple, Block } from './transport.js';
export type { MultibaseDecoder, MultibaseEncoder, } from 'multiformats/bases/interface';
export * from './principal.js';
export * from './capability.js';
export * from './transport.js';
export type { Transport, Principal, PrincipalParser, SigningPrincipal, Phantom, Tuple, DID, Signature, ByteView, Capabilities, Capability, Fact, UCANBlock, UCANLink, Link, Block, Ability, Resource, MultihashDigest, MultihashHasher, };
export type { Transport, Principal, Phantom, Tuple, DID, Signature, ByteView, Capabilities, Capability, Fact, UCANBlock, UCANLink, Link, Block, Ability, Resource, MultihashDigest, MultihashHasher, };
export * as UCAN from '@ipld/dag-ucan';

@@ -27,4 +25,4 @@ /**

}
export interface DelegationOptions<C extends Capabilities, A extends number = number> extends UCANOptions {
issuer: SigningPrincipal<A>;
export interface DelegationOptions<C extends Capabilities> extends UCANOptions {
issuer: Signer;
audience: Principal;

@@ -37,13 +35,13 @@ capabilities: C;

/**
* Map of all the IPLD blocks that where included with this delegation DAG.
* Usually this would be blocks corresponding to proofs, however it may
* also contain other blocks e.g. things that `capabilities` or `facts` may
* link.
* It is not guaranteed to include all the blocks of this DAG, as it represents
* a partial DAG of the delegation desired for transporting.
*
* Also note that map may contain blocks that are not part of this
* delegation DAG. That is because `Delegation` is usually constructed as
* view / selection over the CAR which may contain bunch of other blocks.
*/
* Map of all the IPLD blocks that where included with this delegation DAG.
* Usually this would be blocks corresponding to proofs, however it may
* also contain other blocks e.g. things that `capabilities` or `facts` may
* link.
* It is not guaranteed to include all the blocks of this DAG, as it represents
* a partial DAG of the delegation desired for transporting.
*
* Also note that map may contain blocks that are not part of this
* delegation DAG. That is because `Delegation` is usually constructed as
* view / selection over the CAR which may contain bunch of other blocks.
*/
readonly blocks: Map<string, Block>;

@@ -68,7 +66,7 @@ readonly cid: UCANLink<C>;

export interface InvocationOptions<C extends Capability = Capability> extends UCANOptions {
issuer: SigningPrincipal;
issuer: Signer;
capability: C;
}
export interface IssuedInvocation<C extends Capability = Capability> extends DelegationOptions<[C]> {
readonly issuer: SigningPrincipal;
readonly issuer: Signer;
readonly audience: Principal;

@@ -113,3 +111,3 @@ readonly capabilities: [C];

export declare type ExecuteInvocation<C extends Capability, T extends Record<string, any>, Ability extends string = C['can']> = Ability extends `${infer Base}/${infer Path}` ? ExecuteInvocation<C, T[Base], Path> : T[Ability] extends (input: Invocation<C>) => infer Out ? Out : never;
export declare type Result<T, X extends {
export declare type Result<T extends unknown, X extends {
error: true;

@@ -193,9 +191,48 @@ }> = (T extends null | undefined ? T : never) | (T & {

export declare type Protocol<Scheme extends string = string> = `${Scheme}:`;
export interface URI<P extends Protocol = Protocol> extends URL {
export declare type URI<P extends Protocol = Protocol> = `${P}${string}` & Phantom<{
protocol: P;
href: `${P}${string}`;
}>;
export interface PrincipalParser {
parse(did: UCAN.DID): Verifier;
}
export declare type URIString<P extends URI> = `${URI['protocol']}${string}` & {
protocol?: Protocol;
};
/**
* Represents component that can create a signer from it's archive. Usually
* signer module would provide `from` function and therefor be implementation
* of this interface.
* Library also provides utility functions for combining multiple
* SignerImporters into one.
*/
export interface SignerImporter<Self extends Signer = Signer> {
from(archive: SignerArchive<Self>): Self;
}
export interface Signer<M extends string = string, A extends number = number> extends UCANSigner<M, A> {
/**
* Returns archive of this signer which is byte encoded form when signer key
* is extractable and is {@link SignerInfo} form otherwise. This allows a user
* to store non extractable archives in indexedDB and store extractable
* archives on disk, which matches general expectation that in browsers
* unextratable keys should be used and extractable keys in node.
*
* @example
* ```ts
* const save = async (signer: Signer) => {
* const archive = signer.toArchive()
* if (archive instanceof Uint8Array) {
* await fs.writeFile(KEY_PATH, archive)
* } else {
* await IDB_OBJECT_STORE.add(archive)
* }
* }
* ```
*/
toArchive(): SignerArchive<Signer<M, A>>;
}
export interface SignerInfo<Self extends Signer = Signer> {
readonly did: ReturnType<Self['did']>;
readonly key: CryptoKey;
}
export declare type SignerArchive<Self extends Signer = Signer> = ByteView<Self> | SignerInfo<Self>;
export { Verifier };
export declare type InferInvokedCapability<C extends CapabilityParser<Match<ParsedCapability>>> = C extends CapabilityParser<Match<infer T>> ? T : never;
export declare type Intersection<T> = (T extends any ? (i: T) => void : never) extends (i: infer I) => void ? I : never;
//# sourceMappingURL=lib.d.ts.map
{
"name": "@ucanto/interface",
"description": "interface definitions for ucanto",
"version": "1.0.0",
"version": "2.0.0",
"types": "./dist/src/lib.d.ts",

@@ -21,8 +21,4 @@ "main": "./src/lib.js",

"homepage": "https://github.com/web3-storage/ucanto",
"scripts": {
"typecheck": "tsc --build",
"build": "tsc --build"
},
"dependencies": {
"@ipld/dag-ucan": "3.0.0-beta",
"@ipld/dag-ucan": "^4.0.0-beta",
"multiformats": "^9.8.1"

@@ -40,3 +36,7 @@ },

"type": "module",
"license": "(Apache-2.0 AND MIT)"
}
"license": "(Apache-2.0 AND MIT)",
"scripts": {
"typecheck": "tsc --build",
"build": "tsc --build"
}
}

@@ -8,3 +8,3 @@ import { Ability, Capability, DID, Link, Resource } from '@ipld/dag-ucan'

PrincipalParser,
SigningPrincipal,
Signer,
URI,

@@ -57,12 +57,13 @@ Await,

export interface Decoder<
I extends unknown,
O extends unknown,
export interface Reader<
O = unknown,
I = unknown,
X extends { error: true } = Failure
> {
decode: (input: I) => Result<O, X>
read: (input: I) => Result<O, X>
}
export interface Caveats
extends Record<string, Decoder<unknown, unknown, Failure>> {}
export interface Caveats {
[key: string]: Reader<any, unknown>
}

@@ -137,22 +138,45 @@ export type MatchResult<M extends Match> = Result<M, InvalidCapability>

create(
input: InferCreateOptions<M['value']['with'], M['value']['caveats']>
): Capability<M['value']['can'], M['value']['uri']['href']> &
M['value']['caveats']
input: InferCreateOptions<M['value']['with'], M['value']['nb']>
): M['value']
/**
* Creates an invocation of this capability. Function throws exception if
* non-optional fields are omitted.
*/
invoke(
options: InvokeCapabilityOptions<M['value']['with'], M['value']['caveats']>
): IssuedInvocationView<
Capability<M['value']['can'], M['value']['uri']['href']> &
M['value']['caveats']
>
options: InferInvokeOptions<M['value']['with'], M['value']['nb']>
): IssuedInvocationView<M['value']>
/**
* Creates a delegation of this capability. Please note that all the
* `nb` fields are optional in delegation and only provided ones will
* be validated.
*/
delegate(
options: InferDelegationOptions<M['value']['with'], M['value']['nb']>
): Promise<Delegation<[M['value']]>>
}
export type InferCreateOptions<R extends Resource, C extends {}> = {
with: Resource
caveats?: {}
} & Optionalize<{
export type InferCreateOptions<R extends Resource, C extends {} | undefined> =
// If capability has no NB we want to prevent passing it into
// .create funciton so we make `nb` as optional `never` type so
// it can not be satisfied
keyof C extends never ? { with: R; nb?: never } : { with: R; nb: C }
export type InferInvokeOptions<
R extends Resource,
C extends {} | undefined
> = UCANOptions & { issuer: Signer } & InferCreateOptions<R, C>
export type InferDelegationOptions<
R extends Resource,
C extends {} | undefined
> = UCANOptions & {
issuer: Signer
with: R
caveats: InferCaveatParams<C>
}>
nb?: Partial<InferCreateOptions<R, C>['nb']>
}
export type EmptyObject = { [key: string | number | symbol]: never }
type Optionalize<T> = InferRequried<T> & InferOptional<T>

@@ -168,10 +192,2 @@

export type InvokeCapabilityOptions<
R extends Resource,
C extends {}
> = UCANOptions &
InferCreateOptions<R, C> & {
issuer: SigningPrincipal
}
export interface CapabilityParser<M extends Match = Match> extends View<M> {

@@ -187,3 +203,2 @@ /**

or<W extends Match>(other: MatchSelector<W>): CapabilityParser<M | W>
/**

@@ -268,15 +283,12 @@ * Combines this capability and the other into a capability group. This allows

export interface ParsedCapability<
export type ParsedCapability<
Can extends Ability = Ability,
Resource extends URI = URI,
C extends object = {}
> {
can: Can
with: Resource['href']
uri: Resource
caveats: C
}
> = keyof C extends never
? { can: Can; with: Resource; nb?: C }
: { can: Can; with: Resource; nb: C }
export type InferCaveats<C> = Optionalize<{
[K in keyof C]: C[K] extends Decoder<unknown, infer T, infer _> ? T : never
[K in keyof C]: C[K] extends Reader<infer T, unknown, infer _> ? T : never
}>

@@ -290,5 +302,6 @@

can: A
with: Decoder<Resource, R, Failure>
caveats?: C
with: Reader<R, Resource, Failure>
nb?: C
derives?: Derives<

@@ -318,14 +331,4 @@ ParsedCapability<A, R, InferCaveats<C>>,

export interface IssuingOptions {
export interface ProofResolver extends PrincipalOptions {
/**
* You can provide default set of capabilities per did, which is used to
* validate whether claim is satisfied by `{ with: my:*, can: "*" }`. If
* not provided resolves to `[]`.
*/
my?: (issuer: DID) => Capability[]
}
export interface ProofResolver extends PrincipalOptions, IssuingOptions {
/**
* You can provide a proof resolver that validator will call when UCAN

@@ -339,4 +342,3 @@ * links to external proof. If resolver is not provided validator may not

export interface ValidationOptions<C extends ParsedCapability>
extends CanIssue,
IssuingOptions,
extends Partial<CanIssue>,
PrincipalOptions,

@@ -343,0 +345,0 @@ ProofResolver {

@@ -16,14 +16,15 @@ import {

Signature,
Principal,
Verifier,
Signer as UCANSigner,
} from '@ipld/dag-ucan'
import * as UCAN from '@ipld/dag-ucan'
import type {
Principal,
PrincipalParser,
SigningPrincipal,
} from './principal.js'
import {
CanIssue,
Match,
InvalidAudience,
Unauthorized,
UnavailableProof,
ParsedCapability,
CapabilityParser,
} from './capability.js'

@@ -37,3 +38,2 @@ import type * as Transport from './transport.js'

} from 'multiformats/bases/interface'
export * from './principal.js'
export * from './capability.js'

@@ -44,4 +44,2 @@ export * from './transport.js'

Principal,
PrincipalParser,
SigningPrincipal,
Phantom,

@@ -86,7 +84,4 @@ Tuple,

export interface DelegationOptions<
C extends Capabilities,
A extends number = number
> extends UCANOptions {
issuer: SigningPrincipal<A>
export interface DelegationOptions<C extends Capabilities> extends UCANOptions {
issuer: Signer
audience: Principal

@@ -100,13 +95,13 @@ capabilities: C

/**
* Map of all the IPLD blocks that where included with this delegation DAG.
* Usually this would be blocks corresponding to proofs, however it may
* also contain other blocks e.g. things that `capabilities` or `facts` may
* link.
* It is not guaranteed to include all the blocks of this DAG, as it represents
* a partial DAG of the delegation desired for transporting.
*
* Also note that map may contain blocks that are not part of this
* delegation DAG. That is because `Delegation` is usually constructed as
* view / selection over the CAR which may contain bunch of other blocks.
*/
* Map of all the IPLD blocks that where included with this delegation DAG.
* Usually this would be blocks corresponding to proofs, however it may
* also contain other blocks e.g. things that `capabilities` or `facts` may
* link.
* It is not guaranteed to include all the blocks of this DAG, as it represents
* a partial DAG of the delegation desired for transporting.
*
* Also note that map may contain blocks that are not part of this
* delegation DAG. That is because `Delegation` is usually constructed as
* view / selection over the CAR which may contain bunch of other blocks.
*/
readonly blocks: Map<string, Block>

@@ -140,3 +135,3 @@

extends UCANOptions {
issuer: SigningPrincipal
issuer: Signer
capability: C

@@ -147,3 +142,3 @@ }

extends DelegationOptions<[C]> {
readonly issuer: SigningPrincipal
readonly issuer: Signer
readonly audience: Principal

@@ -280,3 +275,3 @@ readonly capabilities: [C]

export type Result<T, X extends { error: true }> =
export type Result<T extends unknown, X extends { error: true }> =
| (T extends null | undefined ? T : never)

@@ -393,9 +388,68 @@ | (T & { error?: never })

export type Protocol<Scheme extends string = string> = `${Scheme}:`
export interface URI<P extends Protocol = Protocol> extends URL {
protocol: P
href: `${P}${string}`
export type URI<P extends Protocol = Protocol> = `${P}${string}` &
// ⚠️ Without phantom type TS does not seem to retain `P` type
// resulting in `${string}${string}` instead.
Phantom<{
protocol: P
}>
export interface PrincipalParser {
parse(did: UCAN.DID): Verifier
}
export type URIString<P extends URI> = `${URI['protocol']}${string}` & {
protocol?: Protocol
/**
* Represents component that can create a signer from it's archive. Usually
* signer module would provide `from` function and therefor be implementation
* of this interface.
* Library also provides utility functions for combining multiple
* SignerImporters into one.
*/
export interface SignerImporter<Self extends Signer = Signer> {
from(archive: SignerArchive<Self>): Self
}
export interface Signer<M extends string = string, A extends number = number>
extends UCANSigner<M, A> {
/**
* Returns archive of this signer which is byte encoded form when signer key
* is extractable and is {@link SignerInfo} form otherwise. This allows a user
* to store non extractable archives in indexedDB and store extractable
* archives on disk, which matches general expectation that in browsers
* unextratable keys should be used and extractable keys in node.
*
* @example
* ```ts
* const save = async (signer: Signer) => {
* const archive = signer.toArchive()
* if (archive instanceof Uint8Array) {
* await fs.writeFile(KEY_PATH, archive)
* } else {
* await IDB_OBJECT_STORE.add(archive)
* }
* }
* ```
*/
toArchive(): SignerArchive<Signer<M, A>>
}
export interface SignerInfo<Self extends Signer = Signer> {
readonly did: ReturnType<Self['did']>
readonly key: CryptoKey
}
export type SignerArchive<Self extends Signer = Signer> =
| ByteView<Self>
| SignerInfo<Self>
export { Verifier }
export type InferInvokedCapability<
C extends CapabilityParser<Match<ParsedCapability>>
> = C extends CapabilityParser<Match<infer T>> ? T : never
export type Intersection<T> = (T extends any ? (i: T) => void : never) extends (
i: infer I
) => void
? I
: never

@@ -13,3 +13,3 @@ import type {

Principal,
SigningPrincipal,
Signer,
Failure,

@@ -141,3 +141,3 @@ } from './lib.js'

declare var channel: ConnectionView<{ store: Store }>
declare const alice: SigningPrincipal
declare const alice: Signer
declare const bob: Principal

@@ -144,0 +144,0 @@ declare const car: UCAN.Link

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc