make UCAN typing less spaghetti

mcginty · mcginty · commit 40d837ed2638 · 2026-02-02T17:59:43.000-08:00
diff --git a/app/src/nest/qps/ucan/ucan.service.ts b/app/src/nest/qps/ucan/ucan.service.ts
@@ -7,13 +7,16 @@
 import { Injectable, OnModuleInit } from '@nestjs/common'
 import * as ucans from '@ucans/ucans'
 import { createLogger } from '../../app/logger/logger.js'
-import { ServerKeyManagerService } from '../../encryption/server-key-manager.service.js'
 import { AWSSecretsService } from '../../utils/aws/aws-secrets.service.js'
 import { ConfigService } from '../../utils/config/config.service.js'
 import { EnvironmentShort } from '../../utils/config/types.js'
 import {
   DEVICE_TOKEN_URI_SCHEME,
   type UcanValidationResult,
+  type ParsedUcanPayload,
+  type UcanCapability,
+  type UcanResourcePointer,
+  type UcanAbility,
   UcanError,
   UcanErrorCode,
 } from './ucan.types.js'
@@ -26,6 +29,12 @@ const QPS_SIGNING_KEY_SECRET_NAMES: Record<EnvironmentShort, string> = {
   [EnvironmentShort.Prod]: 'qps/prod-signing-key',
 }
 
+// Far-future expiration (year 9999) - effectively no expiration
+// Using a number instead of Infinity because Infinity serializes to null
+const FAR_FUTURE_EXPIRATION = Math.floor(
+  new Date('9999-12-31T23:59:59Z').getTime() / 1000,
+)
+
 @Injectable()
 export class UcanService implements OnModuleInit {
   private keypair: ucans.EdKeypair | undefined
@@ -74,14 +83,10 @@ export class UcanService implements OnModuleInit {
 
     // Audience is set to QPS's own DID since these are self-issued bearer tokens.
     // Any party holding this UCAN can present it to QPS to send push notifications.
-    // Use a far-future expiration (year 9999) since Infinity serializes to null which breaks parsing
-    const farFutureExpiration = Math.floor(
-      new Date('9999-12-31T23:59:59Z').getTime() / 1000,
-    )
     const ucan = await ucans.build({
       issuer: this.keypair,
-      audience: this.qpsDid!, // Self-issued token - QPS is both issuer and audience
-      expiration: farFutureExpiration, // Effectively no expiration
+      audience: this.qpsDid!,
+      expiration: FAR_FUTURE_EXPIRATION,
       capabilities: [
         {
           with: { scheme: 'fcm', hierPart: deviceToken },
@@ -109,74 +114,49 @@ export class UcanService implements OnModuleInit {
     }
 
     try {
-      // Parse the UCAN to inspect its contents
+      this.logger.debug(
+        `Validating UCAN token (length=${token.length}): ${token.substring(0, 50)}...`,
+      )
+
       const parsed = ucans.parse(token)
+      const payload = parsed.payload as ParsedUcanPayload
 
-      if (parsed.payload.iss !== this.qpsDid) {
-        this.logger.warn(
-          `UCAN issuer mismatch: expected ${this.qpsDid}, got ${parsed.payload.iss}`,
-        )
+      // Verify issuer
+      if (!this.verifyIssuer(payload)) {
         return {
           valid: false,
           error: 'Invalid issuer - UCAN was not issued by QPS',
         }
       }
 
-      try {
-        await ucans.validate(token)
-      } catch (validationError) {
-        this.logger.warn(`UCAN validation failed`, validationError)
+      // Validate signature
+      if (!(await this.validateSignature(token))) {
         return {
           valid: false,
           error: 'Invalid UCAN signature or structure',
         }
       }
 
-      const capabilities = parsed.payload.att
-      if (capabilities == null || capabilities.length === 0) {
-        return {
-          valid: false,
-          error: 'No capabilities found in UCAN',
-        }
-      }
-
-      const pushCapability = capabilities.find(
-        (cap: { with: unknown; can: unknown }) => {
-          const can =
-            typeof cap.can === 'string'
-              ? cap.can
-              : `${(cap.can as { namespace: string; segments: string[] }).namespace}/${(cap.can as { namespace: string; segments: string[] }).segments.join('/')}`
-          return can === 'push/send'
-        },
-      )
-
+      // Extract and validate capability
+      const pushCapability = this.findPushCapability(payload.att)
       if (pushCapability == null) {
         return {
           valid: false,
           error: 'No push/send capability found in UCAN',
         }
       }
 
-      // Extract device token from the "with" field
-      const resourceUri =
-        typeof pushCapability.with === 'string'
-          ? pushCapability.with
-          : `${(pushCapability.with as { scheme: string; hierPart: string }).scheme}://${(pushCapability.with as { scheme: string; hierPart: string }).hierPart}`
-
-      if (!resourceUri.startsWith(DEVICE_TOKEN_URI_SCHEME)) {
+      // Extract device token from capability
+      const deviceToken = this.extractDeviceToken(pushCapability)
+      if (deviceToken == null) {
         return {
           valid: false,
-          error: 'Invalid resource URI format in capability',
+          error: 'Invalid device token in UCAN capability',
         }
       }
 
-      const deviceToken = resourceUri.slice(DEVICE_TOKEN_URI_SCHEME.length)
-
-      // Extract bundleId from facts if present
-      const facts = parsed.payload.fct as
-        | Array<{ bundleId?: string }>
-        | undefined
-      const bundleId = facts?.[0]?.bundleId
+      // Extract bundle ID from facts
+      const bundleId = this.extractBundleId(payload.fct)
 
       return {
         valid: true,
@@ -195,6 +175,100 @@ export class UcanService implements OnModuleInit {
     }
   }
 
+  /**
+   * Verify that the UCAN was issued by QPS
+   */
+  private verifyIssuer(payload: ParsedUcanPayload): boolean {
+    if (payload.iss !== this.qpsDid) {
+      this.logger.warn(
+        `UCAN issuer mismatch: expected ${this.qpsDid}, got ${payload.iss}`,
+      )
+      return false
+    }
+    return true
+  }
+
+  /**
+   * Validate the UCAN signature
+   */
+  private async validateSignature(token: string): Promise<boolean> {
+    try {
+      await ucans.validate(token)
+      return true
+    } catch (validationError) {
+      this.logger.warn(`UCAN validation failed`, validationError)
+      return false
+    }
+  }
+
+  /**
+   * Find the push/send capability in the capabilities array
+   */
+  private findPushCapability(
+    capabilities: UcanCapability[],
+  ): UcanCapability | null {
+    if (capabilities.length === 0) {
+      return null
+    }
+
+    return (
+      capabilities.find(cap => {
+        const ability = this.normalizeAbility(cap.can)
+        return ability === 'push/send'
+      }) ?? null
+    )
+  }
+
+  /**
+   * Normalize an ability to a string format
+   */
+  private normalizeAbility(can: UcanAbility | string): string {
+    if (typeof can === 'string') {
+      return can
+    }
+    return `${can.namespace}/${can.segments.join('/')}`
+  }
+
+  /**
+   * Extract the device token from a push capability
+   */
+  private extractDeviceToken(capability: UcanCapability): string | null {
+    const resourceUri = this.normalizeResourcePointer(capability.with)
+
+    if (!resourceUri.startsWith(DEVICE_TOKEN_URI_SCHEME)) {
+      this.logger.warn(`Invalid resource URI scheme: ${resourceUri}`)
+      return null
+    }
+
+    return resourceUri.slice(DEVICE_TOKEN_URI_SCHEME.length)
+  }
+
+  /**
+   * Normalize a resource pointer to a URI string
+   */
+  private normalizeResourcePointer(
+    resource: UcanResourcePointer | string,
+  ): string {
+    if (typeof resource === 'string') {
+      return resource
+    }
+    return `${resource.scheme}://${resource.hierPart}`
+  }
+
+  /**
+   * Extract the bundle ID from UCAN facts
+   */
+  private extractBundleId(
+    facts?: Array<Record<string, unknown>>,
+  ): string | undefined {
+    if (facts == null || facts.length === 0) {
+      return undefined
+    }
+
+    const bundleId = facts[0].bundleId
+    return typeof bundleId === 'string' ? bundleId : undefined
+  }
+
   /**
    * Initialize the QPS signing keypair
    * Retrieves from AWS Secrets Manager if exists, otherwise generates and stores a new one
@@ -206,29 +280,12 @@ export class UcanService implements OnModuleInit {
     )
 
     try {
-      // Try to retrieve existing keypair from AWS
       const existingSecret = await this.awsSecretsService.get(secretName)
 
       if (existingSecret != null && typeof existingSecret === 'string') {
-        this.logger.log(`Found existing QPS signing key`)
-        // Restore keypair from stored secret (base64-encoded secret key)
-        // EdKeypair.fromSecretKey expects a base64 string
-        this.keypair = ucans.EdKeypair.fromSecretKey(existingSecret, {
-          format: 'base64',
-          exportable: true,
-        })
+        this.keypair = this.loadExistingKeypair(existingSecret)
       } else {
-        this.logger.log(
-          `No existing QPS signing key found, generating new keypair`,
-        )
-        // Generate new keypair
-        this.keypair = await ucans.EdKeypair.create({ exportable: true })
-
-        // Store the secret key in AWS Secrets Manager
-        // EdKeypair.export() returns a base64 string by default
-        const secretKeyBase64 = await this.keypair.export('base64')
-        await this.awsSecretsService.create(secretName, secretKeyBase64)
-        this.logger.log(`Stored new QPS signing key in AWS Secrets Manager`)
+        this.keypair = await this.generateAndStoreKeypair(secretName)
       }
 
       this.qpsDid = this.keypair.did()
@@ -239,6 +296,34 @@ export class UcanService implements OnModuleInit {
     }
   }
 
+  /**
+   * Load an existing keypair from a stored secret
+   */
+  private loadExistingKeypair(secretKeyBase64: string): ucans.EdKeypair {
+    this.logger.log(`Found existing QPS signing key`)
+    return ucans.EdKeypair.fromSecretKey(secretKeyBase64, {
+      format: 'base64',
+      exportable: true,
+    })
+  }
+
+  /**
+   * Generate a new keypair and store it in AWS Secrets Manager
+   */
+  private async generateAndStoreKeypair(
+    secretName: string,
+  ): Promise<ucans.EdKeypair> {
+    this.logger.log(`No existing QPS signing key found, generating new keypair`)
+
+    const keypair = await ucans.EdKeypair.create({ exportable: true })
+    const secretKeyBase64 = await keypair.export('base64')
+
+    await this.awsSecretsService.create(secretName, secretKeyBase64)
+    this.logger.log(`Stored new QPS signing key in AWS Secrets Manager`)
+
+    return keypair
+  }
+
   /**
    * Get the AWS secret name for the current environment
    */
diff --git a/app/src/nest/qps/ucan/ucan.types.ts b/app/src/nest/qps/ucan/ucan.types.ts
@@ -39,17 +39,39 @@ export interface UcanValidationResult {
 }
 
 /**
- * Decoded UCAN payload structure (for internal use)
+ * Resource pointer in a UCAN capability
  */
-export interface DecodedUcanPayload {
-  iss: string // Issuer DID
-  aud: string // Audience DID or "*"
-  exp: number | null // Expiration timestamp or null for no expiration
-  att: Array<{
-    with: string // Resource URI (e.g., "fcm://device-token")
-    can: string // Capability (e.g., "push/send")
-  }>
-  fct?: UcanFacts // Facts
+export interface UcanResourcePointer {
+  scheme: string
+  hierPart: string
+}
+
+/**
+ * Ability (action) in a UCAN capability
+ */
+export interface UcanAbility {
+  namespace: string
+  segments: string[]
+}
+
+/**
+ * A single capability in a UCAN token
+ */
+export interface UcanCapability {
+  with: UcanResourcePointer | string
+  can: UcanAbility | string
+}
+
+/**
+ * Parsed UCAN payload structure
+ */
+export interface ParsedUcanPayload {
+  iss: string
+  aud: string
+  exp: number | null
+  att: UcanCapability[]
+  fct?: Array<Record<string, unknown>>
+  prf?: string[]
 }
 
 /**
