iso-ucan 0.0.1

package/src/utils.js

@@ -0,0 +1,375 @@
+import * as dagCbor from '@ipld/dag-cbor'
+import { DID } from 'iso-did'
+import { CID } from 'multiformats/cid'
+import { sha256 } from 'multiformats/hashes/sha2'
+import { z } from 'zod'
+
+import * as Envelope from './envelope.js'
+import * as varsig from './varsig.js'
+
+/**
+ * @import {PayloadSpec} from './types.js'
+ */
+
+/**
+ * Create the signature payload for a given envelope
+ *
+ * @param {import('./types.js').DecodedEnvelope<PayloadSpec>} envelope
+ * @returns
+ */
+export function signaturePayload(envelope) {
+  const payloadTag = /** @type {import('./types.js').PayloadTag} */ (
+    `ucan/${envelope.spec}@${envelope.version}`
+  )
+  const payload = {
+    h: varsig.encode({
+      enc: envelope.enc,
+      alg: envelope.alg,
+    }),
+    [payloadTag]: envelope.payload,
+  }
+  return payload
+}
+
+export function nowInSeconds() {
+  return Math.floor(Date.now() / 1000)
+}
+
+/**
+ *
+ * @param {import('./types.js').DecodedEnvelope<PayloadSpec>} envelope
+ */
+export async function cid(envelope) {
+  const bytes = Envelope.encode({
+    signature: envelope.signature,
+    // @ts-ignore
+    signaturePayload: signaturePayload(envelope),
+  })
+  const hash = await sha256.digest(bytes)
+
+  return CID.create(1, dagCbor.code, hash)
+}
+
+/**
+ * Check if a DID and signature type are compatible
+ *
+ * @param {import('iso-did/types').VerifiableDID} did
+ * @param {import('iso-signatures/types').SignatureType} sigType
+ */
+export function isSigAndDidCompatible(did, sigType) {
+  if (did.verifiableDid.type === 'Ed25519' && sigType === 'Ed25519') {
+    return true
+  }
+
+  if (did.verifiableDid.type === 'secp256k1' && sigType === 'ES256K') {
+    return true
+  }
+
+  if (did.verifiableDid.type === 'P-256' && sigType === 'ES256') {
+    return true
+  }
+
+  if (did.verifiableDid.type === 'P-384' && sigType === 'ES384') {
+    return true
+  }
+
+  if (did.verifiableDid.type === 'P-521' && sigType === 'ES512') {
+    return true
+  }
+
+  if (did.verifiableDid.type === 'RSA' && sigType === 'RS256') {
+    return true
+  }
+  if (did.verifiableDid.type === 'secp256k1' && sigType === 'EIP191') {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Validate the expiration of a UCAN
+ *
+ * @param {number | null} exp
+ */
+export function assertExpiration(exp) {
+  const now = nowInSeconds()
+
+  if (exp !== null && !Number.isSafeInteger(exp)) {
+    throw new TypeError(
+      `UCAN expiration must be null or a safe integer. Received: ${exp}`
+    )
+  }
+
+  if (exp !== null && exp < now) {
+    throw new TypeError(
+      `UCAN expiration must be in the future. Received: ${exp} but current time is ${now}`
+    )
+  }
+}
+
+/**
+ * Validate the not before time of a UCAN
+ *
+ * @param {number} [nbf]
+ */
+export function assertNotBefore(nbf) {
+  if (nbf && nbf > nowInSeconds()) {
+    throw new Error('UCAN not valid yet')
+  }
+}
+
+/**
+ * Validate the issuer and signature of a UCAN
+ *
+ * @param {import('./types.js').DecodedEnvelope<PayloadSpec>} envelope
+ * @param {import('iso-did').Resolver} [didResolver]
+ */
+export async function validateIssuerAndSignature(envelope, didResolver) {
+  const issuer = await DID.fromString(envelope.payload.iss, didResolver)
+  if (!isSigAndDidCompatible(issuer, envelope.alg)) {
+    throw new Error(
+      `UCAN issuer type mismatch: DID ${issuer.verifiableDid.type} and Signature ${envelope.alg} are not compatible`
+    )
+  }
+
+  return issuer
+}
+
+/**
+ * Verify the signature of a UCAN and that issuer is compatible with the signature
+ *
+ * @param {import('./types.js').DecodedEnvelope<PayloadSpec>} envelope
+ * @param {import('iso-signatures/verifiers/resolver.js').Resolver} signatureVerifierResolver
+ * @param {import('iso-did').Resolver} [didResolver]
+ */
+export async function verifySignature(
+  envelope,
+  signatureVerifierResolver,
+  didResolver
+) {
+  const issuer = await validateIssuerAndSignature(envelope, didResolver)
+  const isVerified = await signatureVerifierResolver.verify({
+    signature: envelope.signature,
+    message: dagCbor.encode(signaturePayload(envelope)),
+    did: issuer,
+    type: envelope.alg,
+  })
+
+  if (!isVerified) {
+    throw new Error('UCAN signature verification failed')
+  }
+
+  return true
+}
+
+/**
+ * Asserts that a UCAN command string is syntactically valid.
+ * If the command is invalid, it throws a descriptive error.
+ *
+ * Rules:
+ * - Commands MUST begin with a slash (/).
+ * - Commands MUST be lowercase.
+ * - A trailing slash MUST NOT be present, unless the command is exactly "/".
+ * - Segments MUST be separated by a slash (e.g., no empty segments like "//").
+ *
+ * @param {string} command The command string to validate.
+ * @throws {Error} If the command is syntactically invalid.
+ * @returns {void} Does not return a value on success.
+ */
+export function assertIsValidCommand(command) {
+  // Rule: Must be a string
+  if (typeof command !== 'string') {
+    throw new TypeError(
+      `Invalid command: Input must be a string, but received type ${typeof command}`
+    )
+  }
+
+  // Rule: Must begin with a slash
+  if (!command.startsWith('/')) {
+    throw new TypeError(
+      `Invalid command: Must begin with a slash (/). Received: "${command}"`
+    )
+  }
+
+  // Rule: No trailing slash, unless the command is exactly "/"
+  if (command.length > 1 && command.endsWith('/')) {
+    throw new TypeError(
+      `Invalid command: Must not have a trailing slash. Received: "${command}"`
+    )
+  }
+
+  // Rule: Must be lowercase
+  if (command !== command.toLowerCase()) {
+    throw new TypeError(
+      `Invalid command: Must be lowercase. Received: "${command}"`
+    )
+  }
+
+  // Rule: No empty segments
+  if (command.includes('//')) {
+    throw new TypeError(
+      `Invalid command: Must not contain empty segments (e.g., "//"). Received: "${command}"`
+    )
+  }
+
+  // If no error was thrown, the command is valid.
+}
+
+/**
+ * Assert that the input is a Uint8Array.
+ *
+ * @param {unknown} nonce The value to check.
+ * @throws {Error} If nonce is not a Uint8Array.
+ * @returns {void}
+ *
+ * @example
+ * ```ts twoslash
+ * import { assertNonce } from 'iso-ucan/utils'
+ * assertNonce(new Uint8Array([1,2,3])) // ok
+ * assertNonce('foo') // throws
+ * ```
+ */
+export function assertNonce(nonce) {
+  if (!(nonce instanceof Uint8Array)) {
+    throw new TypeError(
+      `Invalid nonce: Expected Uint8Array, got ${Object.prototype.toString.call(nonce)}`
+    )
+  }
+}
+/**
+ * Assert that args is a JSON serializable object.
+ *
+ * @param {unknown} args
+ */
+export function assertArgs(args) {
+  const parsed = cborObject.safeParse(args)
+  if (parsed.error) {
+    const pretty = z.prettifyError(parsed.error)
+
+    throw new TypeError(`Invalid args: ${pretty}`, { cause: parsed.error })
+  }
+}
+
+/**
+ * Assert that the input is a Record<PropertyKey, unknown>.
+ *
+ * @param {unknown} meta - The value to check.
+ * @throws {Error} If meta is not a Record<PropertyKey, unknown>.
+ * @returns {void}
+ */
+export function assertMeta(meta) {
+  if (meta) {
+    const parsed = cborObject.safeParse(meta)
+    if (parsed.error) {
+      const pretty = z.prettifyError(parsed.error)
+
+      throw new TypeError(`Invalid meta: ${pretty}`, { cause: parsed.error })
+    }
+  }
+}
+
+/**
+ * Assert that the input is not revoked.
+ *
+ * @param {import('multiformats/cid').CID} cid
+ * @param {(cid: CID) => Promise<boolean>} [isRevokedFn]
+ */
+export async function assertNotRevoked(cid, isRevokedFn) {
+  isRevokedFn = isRevokedFn ?? (async () => false)
+  const isRevoked = await isRevokedFn(cid)
+  if (isRevoked) {
+    throw new Error('UCAN revoked')
+  }
+}
+
+/**
+ * Expiration or TTL (default 300 seconds)
+ *
+ * @param {object} options
+ * @param {number | null} [options.exp]
+ * @param {number} [options.ttl]
+ */
+export function expOrTtl({ exp, ttl }) {
+  if (exp === null) {
+    return exp
+  }
+  const currentTimeInSeconds = Math.floor(Date.now() / 1000)
+  const expiration = exp ?? currentTimeInSeconds + (ttl ?? 300)
+
+  return expiration
+}
+
+export const cborValue =
+  /** @type {typeof z.lazy<z.ZodType<import('../src/types.js').CborValue>>} */ (
+    z.lazy
+  )(() => {
+    return z.union([
+      z.string(),
+      z.number(),
+      z.boolean(),
+      z.null(),
+      z.boolean(),
+      z.bigint(),
+      z.instanceof(Uint8Array),
+      z.array(cborValue),
+      z.record(z.string(), cborValue),
+    ])
+  })
+export const cborObject = z.record(z.string(), cborValue)
+
+export const selector = z.union([
+  z.literal('.'),
+  z.templateLiteral([z.literal('.'), z.string()]),
+])
+
+/**
+ * @typedef {z.infer<typeof selector>} Selector
+ */
+
+/**
+ * Statement
+ */
+export const statement =
+  /** @type {typeof z.lazy<z.ZodType<import('../src/types.js').Statement<unknown>>>} */ (
+    z.lazy
+    // @ts-ignore
+  )(() => {
+    return z.union([
+      z.tuple([
+        z.union([z.literal('=='), z.literal('!=')]),
+        selector,
+        z.unknown(),
+      ]), // Equality
+      z.tuple([
+        z.union([
+          z.literal('<'),
+          z.literal('<='),
+          z.literal('>'),
+          z.literal('>='),
+        ]),
+        selector,
+        z.number(),
+      ]), // Inequality
+      z.tuple([z.literal('like'), selector, z.string()]), // Like
+      z.tuple([z.literal('not'), statement]),
+      z.tuple([z.literal('and'), z.array(statement)]),
+      z.tuple([z.literal('or'), z.array(statement)]),
+      z.tuple([z.literal('all'), z.string(), statement]),
+      z.tuple([z.literal('any'), z.string(), statement]),
+    ])
+  })
+
+export const policySchema = z.array(statement)
+
+/**
+ * @param {unknown} policy
+ */
+export function assertPolicy(policy) {
+  const parsed = policySchema.safeParse(policy)
+  if (parsed.error) {
+    const pretty = z.prettifyError(parsed.error)
+
+    throw new TypeError(`Invalid policy: ${pretty}`, { cause: parsed.error })
+  }
+}

package/src/varsig.js

@@ -0,0 +1,157 @@
+import { IOBuffer } from 'iobuffer'
+import { hex } from 'iso-base/rfc4648'
+import { equals } from 'iso-base/utils'
+import { varint } from 'iso-base/varint'
+
+export const VARSIG = 0x34
+export const VERSION = 0x01
+export const EIP191_ENCODING = 0xe191
+
+/**
+ * @type {Record<number, import('./types.js').VarsigEncoding>}
+ */
+export const CODE_ENCODING = /** @types  {const} */ {
+  0x5f: 'RAW',
+  0x71: 'DAG-CBOR',
+}
+
+/**
+ * @type {Record<number, string>}
+ */
+export const SIG_PREFIX = /** @type {const} */ ({
+  0x12_05: 'RSA',
+  0xed: 'EdDSA',
+  0xec: 'ECDSA',
+})
+
+/**
+ * Varint encoding for signature algorithms and encodings.
+ *
+ * @type {Record<'VARSIG' | 'VERSION' | import('./types.js').VarsigEncoding | import('./types.js').VarsigAlgorithm, number[]  >}
+ */
+const VARINT = {
+  VARSIG: [52],
+  VERSION: [1],
+
+  RAW: [95],
+  'DAG-CBOR': [113],
+
+  /** Presets */
+  // rsa(2b)+SHA2-256(1b)+256(1b)
+  RS256: [133, 36, 18, 128, 2],
+  // eddsa(2b)+edwards25519(2b)+SHA2-512(1b)
+  Ed25519: [237, 1, 237, 1, 19],
+  // ECDSA(2b) + p256(2b)   + SHA2-256(1b)
+  ES256: [236, 1, 128, 36, 18],
+  // ECDSA(2b) + p384(2b)   + SHA2-384(1b)
+  ES384: [236, 1, 129, 36, 32],
+  // ECDSA(2b) + p512(2b)   + SHA2-512(1b)
+  ES512: [236, 1, 130, 36, 19],
+  // ECDSA(2b) + secp256k1(2b)  + SHA2-256(1b)
+  ES256K: [236, 1, 231, 1, 18],
+  // ECDSA(2b) + secp256k1(2b) + keccak-256(1b) + eip191-encoding(3b)
+  EIP191: [236, 1, 231, 1, 27, 145, 195, 3],
+}
+
+/**
+ * @param {import('./types.js').VarsigOptions} options
+ */
+export function encode(options) {
+  const enc = VARINT[options.enc]
+  if (!enc) {
+    throw new TypeError(`Unsupported encoding ${options.enc}`)
+  }
+
+  const alg = VARINT[options.alg]
+  if (!alg) {
+    throw new TypeError(`Unsupported algorithm ${options.alg}`)
+  }
+
+  return Uint8Array.from([...VARINT.VARSIG, ...VARINT.VERSION, ...alg, ...enc])
+}
+
+/**
+ * @param {Uint8Array<ArrayBufferLike>} bytes
+ */
+function getEncoding(bytes) {
+  const [code] = varint.decode(bytes)
+  const enc = CODE_ENCODING[code]
+  if (!enc) {
+    throw new TypeError(`Unsupported encoding 0x${code.toString(16)}`)
+  }
+  return enc
+}
+
+/**
+ * @param {Uint8Array<ArrayBufferLike>} bytes
+ * @param {import('./types.js').VarsigAlgorithm[]} presets
+ */
+function getPreset(bytes, presets) {
+  for (const preset of presets) {
+    if (equals(bytes, Uint8Array.from(VARINT[preset]))) {
+      return preset
+    }
+  }
+  throw new TypeError(`Unsupported preset ${bytes}`)
+}
+
+/**
+/**
+ * Decode varsig header
+ *
+ * @param {Uint8Array} buf
+ * @returns {import('./types.js').DecodeOutput}
+ */
+export function decode(buf) {
+  const bytes = new IOBuffer(buf)
+  const varsig = bytes.readBytes(1)
+  if (varsig[0] !== VARINT.VARSIG[0]) {
+    throw new TypeError(
+      `Invalid varsig sigil expected 0x${VARSIG.toString(16)} got 0x${hex.encode(varsig)}`
+    )
+  }
+
+  const version = bytes.readBytes(1)
+  if (version[0] !== VARINT.VERSION[0]) {
+    throw new TypeError(
+      `Invalid version sigil expected 0x${VERSION.toString(16)} got 0x${hex.encode(version)}`
+    )
+  }
+  const [code] = varint.decode(buf, 2)
+
+  switch (SIG_PREFIX[code]) {
+    case 'RSA': {
+      return {
+        alg: getPreset(bytes.readBytes(5), ['RS256']),
+        enc: getEncoding(bytes.readBytes(1)),
+      }
+    }
+    case 'EdDSA': {
+      return {
+        alg: getPreset(bytes.readBytes(5), ['Ed25519']),
+        enc: getEncoding(bytes.readBytes(1)),
+      }
+    }
+    case 'ECDSA': {
+      const isEIP191 = varint.decode(buf, 2 + 5)[0] === EIP191_ENCODING
+      if (isEIP191) {
+        return {
+          alg: getPreset(bytes.readBytes(8), ['EIP191']),
+          enc: getEncoding(bytes.readBytes(1)),
+        }
+      }
+
+      return {
+        alg: getPreset(bytes.readBytes(5), [
+          'ES256',
+          'ES256K',
+          'ES384',
+          'ES512',
+        ]),
+        enc: getEncoding(bytes.readBytes(1)),
+      }
+    }
+    default:
+      throw new TypeError(`Unsupported algorithm ${code}`)
+  }
+}