What do we name the ways we check UCANs?

[bgins]

We've discussed on a couple of occasions which names ts-ucan should use for functions that check UCANs. This discussion aims to bring the considerations together and discuss them all in one place.

We need some name to discuss the general concept, and I've chosen the term "check" because it seems sufficiently generic to cover nearly anything. We can consider an alternative term if we find "check" frames the discussion in an unproductive way.

What can we check?

We can check if a UCAN is

• Decodable. The header, payload, and signature can be decoded and are separated by ..
• Properly structured. The UCAN has all required fields in the header and payload. All fields in the header and payload are correctly typed.
• Too early. The nbf time is in the future.
• Expired. The exp time has passed.
• Active. The nbf is in the past and the exp is in the future.
• Signed. The header + payload was signed by the the issuer.
• Has authority. All capabilities are delegated by proof(s) or the issuer originates them by parenthood.

Some UCAN checks are specific to one capability

• Has authority. The capability is delegated by proof(s) or the issuer originates them by parenthood.
• Active. The nbf to exp time bounds on the UCAN fall within the time bounds of a proof that delegates the capability.
• Can delegate. Can we use a UCAN to delegate a capability.

We can safely use a capability that checks out even if other capabilities in a UCAN do not.

Does this summary cover everything we can check? Is it accurate? Please mention anything that is missing or incorrect in the discussion below.

What names do we use now?

validate

ts-ucan/src/token.ts

Lines 286 to 304 in 2debb4e

	export interface ValidateOptions {
	checkIssuer?: boolean
	checkIsExpired?: boolean
	checkIsTooEarly?: boolean
	checkSignature?: boolean
	}
	/**
	* Parse & Validate **one layer** of a UCAN.
	* This doesn't validate attenutations and doesn't validate the whole UCAN chain.
	*
	* By default, this will check the signature and time bounds.
	*
	* @param encodedUcan the JWT-encoded UCAN to validate
	* @param options an optional parameter to configure turning off some validation options
	* @returns the parsed & validated UCAN (one layer)
	* @throws Error if the UCAN is invalid
	*/
	export async function validate(encodedUcan: string, options?: ValidateOptions): Promise<Ucan> {

isExpired

ts-ucan/src/token.ts

Lines 339 to 346 in 2debb4e

	/**
	* Check if a UCAN is expired.
	*
	* @param ucan The UCAN to validate
	*/
	export function isExpired(ucan: Ucan): boolean {
	return ucan.payload.exp <= Math.floor(Date.now() / 1000)
	}

isTooEarly

ts-ucan/src/token.ts

Lines 348 to 356 in 2debb4e

	/**
	* Check if a UCAN is not active yet.
	*
	* @param ucan The UCAN to validate
	*/
	export const isTooEarly = (ucan: Ucan): boolean => {
	if (ucan.payload.nbf == null) return false
	return ucan.payload.nbf > Math.floor(Date.now() / 1000)
	}

Chained.fromToken

ts-ucan/src/chained.ts

Lines 22 to 34 in 2debb4e

	/**
	* Validate a UCAN chain from a given JWT-encoded UCAN.
	*
	* This will validate
	* - The encoding
	* - The signatures (unless turned off in the `options`)
	* - The UCAN time bounds (unless turned off in the `options`)
	* - The audience from parent proof UCANs matching up with the issuer of child UCANs
	*
	* @returns A promise of a deeply-validated, deeply-parsed UCAN.
	* @throws If the UCAN chain can't be validated.
	*/
	static async fromToken(encodedUcan: string, options?: token.ValidateOptions): Promise<Chained> {

hasCapability

ts-ucan/src/attenuation.ts

Lines 184 to 195 in 2debb4e

	/**
	* Check if a UCAN chain has a specific `Capability`.
	*
	* This check depends on the given capability info.
	* We need to check the originator of the capability,
	* otherwise anyone could pretend to have these rights.
	*/
	export function hasCapability<Cap>(
	semantics: CapabilitySemantics<Cap>,
	capability: CapabilityWithInfo<Cap>,
	ucan: Chained
	): CapabilityWithInfo<Cap> | false {

canDelegate

ts-ucan/src/attenuation.ts

Lines 81 to 99 in 2debb4e

	export function canDelegate<A>(semantics: CapabilitySemantics<A>, capability: A, ucan: Chained): boolean {
	for (const cap of capabilities(ucan, semantics)) {
	if (isCapabilityEscalation(cap)) {
	continue
	}
	const delegated = semantics.tryDelegating(cap.capability, capability)
	if (isCapabilityEscalation(delegated)) {
	continue
	}
	if (delegated != null) {
	return true
	}
	}
	return false
	}

We have an issue open for an unsafe decoding function: #62

Discuss

A few initial questions that we can consider

• What are our thoughts on the names we use now?
• Could the current names be improved? If so, how?
• On what basis do we determine good names?

[matheus23]

In general, UCANs, unlike traditional access keys, aren't just valid or invalid:
UCANs have capabilities, and as a service or someone who wants to check UCAN validity, you need to make sure that the UCAN gives the expected capabilities.

I think the fact that we have a bunch of utilities for checking different things about UCANs with a more ore less yes/no answer other than checking for capabilities has been extremely confusing for users.
We should reduce the API surface area:

• get rid of fromToken
• hide the validate function, and instead promote functions like hasCapability (or whatever we come up with for checking capabilities)

---

I'm sorry I know that this doesn't really help with the naming discussion here, and I have wisdom for how to determine good names, but I think it's a related thought. Reducing the API surface area is a way of making it easier for users to consume ts-ucan just like better names are :)

(And sorry for polluting the API surface area when I was working on ts-ucan so far 👀 )

[icidasset]

I like the idea of promoting hasCapability. But of course a UCAN needs to be valid before we check the capabilities. So, maybe we should have a function that does both, and hasCapability isn't the right name anymore. What if we call it verify or something similar? What about something like:

import * as ucans from "ucans"

ucans.verify(ucan || encodedUcan || ucanChain, {
  originator: ...,
  expiresAt: ...,
  capabilities: [ { semantics, capability } ],
  facts: [] // maybe verify facts somehow? 🤷‍♂️
})

[matheus23]

LOL I love how this turned into an API design discussion :D

Yes! I think adding a verify function like that is a great idea. Also, let's not pass it expiresAt and notBefore, but instead pass it a invocationTime parameter which is optional and if not present, defaults to the current time.

Facts are a different beast. Let's wait for more experiences with use cases for that or maybe check back with Brooke on that. (At least I don't feel comfortable figuring out an API for them).

[matheus23]

Also, we could default to equality-style capability semantics where delegation is allowed if capabilities deep-equal.

[bgins]

Agreed, a verify function would be a great addition. 💯

The name will be familiar to developers coming from other libraries. Our top two most-used libraries from the comment below use verify:

• jsonwebtoken: https://www.npmjs.com/package/jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback
• jose: https://www.npmjs.com/package/jose (for JWT and JWS)

[matheus23]

Actually, I've looked at what we've got out there and we're using UCAN fact in the AWAKE protocol.
Our haskell code already has a containsFact function (which should better be called checkFacts. Also here's how it's used). I guess we could do a similar interface: e.g. pass a function checkFacts: (facts: Fact[]) => "ok" | { error: string }

[bgins]

One consideration when selecting names is familiarity. What names do developers know from using other auth libraries?

A quick search of NPM with some manual filtering ranks these libraries as the most widely used (by weekly download), general purpose JWT libraries:

1. jsonwebtoken: https://www.npmjs.com/package/jsonwebtoken
2. jose: https://www.npmjs.com/package/jose
3. express-jwt: https://www.npmjs.com/package/express-jwt
4. passport-jwt: https://www.npmjs.com/package/passport-jwt
5. jwt-simple: https://www.npmjs.com/package/jwt-simple
6. njwt: https://www.npmjs.com/package/njwt

We should consider the context developers have from using these libraries. On the other hand, we don't need to mimic the names they use exactly. UCAN is different, and we should frame our names accordingly.