Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AuthService
✓ import { AuthService } from 'feathers-ucan';
✗ const { AuthService } = require('feathers-ucan');
Most modern FeathersJS packages, including this one, primarily use ES Modules. Use named imports.
UcanStrategy
✓ import { UcanStrategy } from 'feathers-ucan';
✗ import UcanStrategy from 'feathers-ucan';
The `UcanStrategy` class is a named export, not a default export.
genCapability
✓ import { genCapability } from 'feathers-ucan';
✗ import { GenCapability } from 'feathers-ucan';
This utility function for generating UCAN capabilities is a named export and follows camelCase naming.
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.
import { feathers } from '@feathersjs/feathers';
import express from '@feathersjs/express';
import { UcanStrategy } from 'feathers-ucan';
import { AuthenticationService, LocalStrategy, expressOauth } from '@feathersjs/authentication';
import { NotAuthenticated } from '@feathersjs/errors';
interface AppConfig {
authentication: {
secret: string;
entity: string;
service: string;
authStrategies: string[];
jwtOptions: {
header: { typ: string };
audience: string;
issuer: string;
algorithm: string;
expiresIn: string;
};
client_ucan?: string;
ucan_aud?: string;
};
}
const app = express(feathers());
// Minimal configuration for authentication service
app.set('authentication', {
secret: process.env.AUTH_SECRET ?? 'super-secret-secret-key-insecure-for-production',
entity: 'user',
service: 'users',
authStrategies: ['ucan', 'local'],
jwtOptions: {
header: { typ: 'access' },
audience: 'https://your-app.com',
issuer: 'feathers',
algorithm: 'HS256',
expiresIn: '1d'
},
// feathers-ucan specific config (defaults for example)
client_ucan: 'did:key:example-client',
ucan_aud: 'did:key:example-app-server'
} as AppConfig['authentication']);
// Register the standard Feathers authentication service
app.use('/authentication', new AuthenticationService(app));
// Register UCAN and Local strategies
const authService = app.service('authentication') as AuthenticationService; // Cast for types
authService.register('ucan', new UcanStrategy());
authService.register('local', new LocalStrategy());
// Enable Feathers Express middleware
app.configure(express.rest());
app.configure(expressOauth());
// Basic user service for local strategy (not strictly needed for UCAN but completes the example)
app.use('/users', {
async create(data: any) { return { id: 1, email: data.email, password: data.password }; },
async get(id: string) {
if (id === '1') return { id: 1, email: 'test@example.com' };
throw new NotAuthenticated('User not found');
}
});
// Add authentication hooks
app.service('authentication').hooks({
before: {
create: [
AuthenticationService.hooks.authenticate(['ucan', 'local'])
]
}
});
app.listen(3030).on('listening', () => {
console.log('Feathers application listening on http://localhost:3030');
console.log('Try authenticating with a UCAN token or local strategy.');
console.log('Example: POST to http://localhost:3030/authentication with { strategy: "local", email: "test@example.com", password: "password" }');
});
Errors
Common errors & fixes
Error: No authentication strategy 'ucan' registered.
The `UcanStrategy` was not registered with the Feathers `AuthenticationService` or was registered incorrectly.
fixEnsure you have `app.use('/authentication', new AuthenticationService(app));` and then `app.service('authentication').register('ucan', new UcanStrategy());` in your Feathers configuration. FeathersError: NotAuthenticated - UCAN verification failed: Invalid audience
The `aud` (audience) field in the provided UCAN token does not match the `authentication.ucan_aud` configuration value set in your Feathers application.
fixVerify 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', { ... });`. TypeError: Cannot read properties of undefined (reading 'client_ucan') OR Cannot read properties of undefined (reading 'ucan_aud')
The `authentication` configuration in your Feathers application is missing the `client_ucan` or `ucan_aud` properties, which are required by `feathers-ucan`.
fixAdd both `client_ucan` and `ucan_aud` to your Feathers `authentication` configuration, typically in `config/default.json` or by calling `app.set('authentication', { ... });`. Audit
Dependencies
@ucans/ucansrequiredCore dependency for UCAN token functionality and capability management.
@feathersjs/authenticationrequiredProvides the base Feathers authentication service and strategy registration mechanism.
@feathersjs/expressoptionalUsed for Feathers' Express integration, including OAuth middleware (`expressOauth`).