{"id":16818,"library":"feathers-ucan","title":"Feathers UCAN Authentication","description":"feathers-ucan is an extension for FeathersJS that integrates User Controlled Authorization Networks (UCAN) tokens into the existing JWT authentication system. Currently at version 0.1.45, the library is in an early, active development stage, with the README indicating that UCAN concepts are still emerging and the implementation is tailored to specific project needs, suggesting an iterative release cadence. Its key differentiators include the ability to register a `UcanStrategy` with the Feathers authentication service, utilities for generating UCAN capabilities (`genCapability`), and a `CoreCall` class designed to manage and propagate 'core' authentication parameters across internal service calls, aiming to optimize performance by avoiding redundant authentication checks. The package strives to remain unopinionated while providing a structured way to leverage UCAN's decentralized authorization model within a Feathers application.","status":"active","version":"0.1.45","language":"javascript","source_language":"en","source_url":"https://github.com/ha6755ad/symbol-utils#readme","tags":["javascript","typescript"],"install":[{"cmd":"npm install feathers-ucan","lang":"bash","label":"npm"},{"cmd":"yarn add feathers-ucan","lang":"bash","label":"yarn"},{"cmd":"pnpm add feathers-ucan","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for UCAN token functionality and capability management.","package":"@ucans/ucans","optional":false},{"reason":"Provides the base Feathers authentication service and strategy registration mechanism.","package":"@feathersjs/authentication","optional":false},{"reason":"Used for Feathers' Express integration, including OAuth middleware (`expressOauth`).","package":"@feathersjs/express","optional":true}],"imports":[{"note":"Most modern FeathersJS packages, including this one, primarily use ES Modules. Use named imports.","wrong":"const { AuthService } = require('feathers-ucan');","symbol":"AuthService","correct":"import { AuthService } from 'feathers-ucan';"},{"note":"The `UcanStrategy` class is a named export, not a default export.","wrong":"import UcanStrategy from 'feathers-ucan';","symbol":"UcanStrategy","correct":"import { UcanStrategy } from 'feathers-ucan';"},{"note":"This utility function for generating UCAN capabilities is a named export and follows camelCase naming.","wrong":"import { GenCapability } from 'feathers-ucan';","symbol":"genCapability","correct":"import { genCapability } from 'feathers-ucan';"}],"quickstart":{"code":"import { feathers } from '@feathersjs/feathers';\nimport express from '@feathersjs/express';\nimport { UcanStrategy } from 'feathers-ucan';\nimport { AuthenticationService, LocalStrategy, expressOauth } from '@feathersjs/authentication';\nimport { NotAuthenticated } from '@feathersjs/errors';\n\ninterface AppConfig {\n  authentication: {\n    secret: string;\n    entity: string;\n    service: string;\n    authStrategies: string[];\n    jwtOptions: {\n      header: { typ: string };\n      audience: string;\n      issuer: string;\n      algorithm: string;\n      expiresIn: string;\n    };\n    client_ucan?: string;\n    ucan_aud?: string;\n  };\n}\n\nconst app = express(feathers());\n\n// Minimal configuration for authentication service\napp.set('authentication', {\n  secret: process.env.AUTH_SECRET ?? 'super-secret-secret-key-insecure-for-production',\n  entity: 'user',\n  service: 'users',\n  authStrategies: ['ucan', 'local'],\n  jwtOptions: {\n    header: { typ: 'access' },\n    audience: 'https://your-app.com',\n    issuer: 'feathers',\n    algorithm: 'HS256',\n    expiresIn: '1d'\n  },\n  // feathers-ucan specific config (defaults for example)\n  client_ucan: 'did:key:example-client',\n  ucan_aud: 'did:key:example-app-server'\n} as AppConfig['authentication']);\n\n// Register the standard Feathers authentication service\napp.use('/authentication', new AuthenticationService(app));\n\n// Register UCAN and Local strategies\nconst authService = app.service('authentication') as AuthenticationService; // Cast for types\nauthService.register('ucan', new UcanStrategy());\nauthService.register('local', new LocalStrategy());\n\n// Enable Feathers Express middleware\napp.configure(express.rest());\napp.configure(expressOauth());\n\n// Basic user service for local strategy (not strictly needed for UCAN but completes the example)\napp.use('/users', {\n  async create(data: any) { return { id: 1, email: data.email, password: data.password }; },\n  async get(id: string) {\n    if (id === '1') return { id: 1, email: 'test@example.com' };\n    throw new NotAuthenticated('User not found');\n  }\n});\n\n// Add authentication hooks\napp.service('authentication').hooks({\n  before: {\n    create: [\n      AuthenticationService.hooks.authenticate(['ucan', 'local'])\n    ]\n  }\n});\n\napp.listen(3030).on('listening', () => {\n  console.log('Feathers application listening on http://localhost:3030');\n  console.log('Try authenticating with a UCAN token or local strategy.');\n  console.log('Example: POST to http://localhost:3030/authentication with { strategy: \"local\", email: \"test@example.com\", password: \"password\" }');\n});\n","lang":"typescript","description":"This quickstart initializes a basic FeathersJS application with an authentication service, registers the `UcanStrategy` alongside a `LocalStrategy`, and sets up minimal configuration required for `feathers-ucan` to function. It demonstrates how to integrate UCAN into the standard Feathers authentication flow, enabling the application to process and verify UCAN tokens."},"warnings":[{"fix":"Pin exact versions in your `package.json` (e.g., `\"feathers-ucan\": \"0.1.45\"`). Review release notes carefully for any updates before upgrading.","message":"This package is in a pre-1.0 state (0.1.x), meaning API changes, including breaking ones, may occur without strictly adhering to SemVer conventions. The README itself notes UCAN tokens are 'still emerging'.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Thoroughly understand the `core` params propagation and `CoreCall` class, ensuring consistent and correct context passing in internal calls. Incorrect usage can bypass security or cause unexpected behavior.","message":"The `core` params mechanism described in the README (e.g., `client_ucan`, `ucan_aud`, and the `CoreCall` class) is an internal optimization for managing authentication context. Mismanaging these parameters, especially across internal service calls, can lead to authentication failures or loss of user context.","severity":"gotcha","affected_versions":"*"},{"fix":"Implement robust authorization hooks that parse and validate the capabilities within a UCAN token against the requested service method and data. Use `genCapability` to ensure capabilities are correctly formed and understood by your application.","message":"UCAN tokens are unopinionated, and their effective use, especially regarding capabilities (`caps`), requires careful design specific to your application's authorization model. Simply verifying a UCAN token does not automatically grant appropriate access; capabilities must be checked.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you have `app.use('/authentication', new AuthenticationService(app));` and then `app.service('authentication').register('ucan', new UcanStrategy());` in your Feathers configuration.","cause":"The `UcanStrategy` was not registered with the Feathers `AuthenticationService` or was registered incorrectly.","error":"Error: No authentication strategy 'ucan' registered."},{"fix":"Verify that the UCAN token being sent by the client has an `aud` field that precisely matches the `authentication.ucan_aud` configuration in your Feathers `default.json` or `app.set('authentication', { ... });`.","cause":"The `aud` (audience) field in the provided UCAN token does not match the `authentication.ucan_aud` configuration value set in your Feathers application.","error":"FeathersError: NotAuthenticated - UCAN verification failed: Invalid audience"},{"fix":"Add both `client_ucan` and `ucan_aud` to your Feathers `authentication` configuration, typically in `config/default.json` or by calling `app.set('authentication', { ... });`.","cause":"The `authentication` configuration in your Feathers application is missing the `client_ucan` or `ucan_aud` properties, which are required by `feathers-ucan`.","error":"TypeError: Cannot read properties of undefined (reading 'client_ucan') OR Cannot read properties of undefined (reading 'ucan_aud')"}],"ecosystem":"npm","meta_description":null}