Skip to main content

Quik Framework :: Passport

@quik/passport integrates Passport.js with Quik authorization and HTTP modules. It supports built-in Basic and Bearer strategies, custom OAuth providers, and passkey flows.

For ready-to-use passkey HTTP endpoints, load @quik/passport-passkey. Scalar passkey helper support is built into @quik/passport.

Installation​

pnpm add @quik/passport

What The Module Does​

  • Loads module locales for passkey-related errors.
  • Registers Passport runtime middleware into the Express engine.
  • Registers built-in strategies (basic, bearer, passkey).
  • Registers OAuth providers from the providers store.

Configuration​

Passkey support uses Quik config keys under auth.passkey:

  • auth.passkey.challenge.timeToLiveMs default 300000.
  • auth.passkey.relyingParty.id default localhost.
  • auth.passkey.relyingParty.name default Quik.

relyingParty.id means the domain identity for your app in WebAuthn (for example example.com). relyingParty.name is the user-facing app name shown by passkey clients and authenticators.

These keys can be provided in your app defaults/environment pipeline.

Scalar helper support uses docs.scalar.passkey.*:

  • docs.scalar.passkey.enabled
  • docs.scalar.passkey.title
  • docs.scalar.passkey.description
  • docs.scalar.passkey.begin.url
  • docs.scalar.passkey.begin.method
  • docs.scalar.passkey.verify.url
  • docs.scalar.passkey.verify.method
  • docs.scalar.passkey.authorization.headerName
  • docs.scalar.passkey.authorization.scheme
  • docs.scalar.passkey.authorization.tokenPath
  • docs.scalar.passkey.includeCredentials

Basic Endpoint Protection​

import { Passport } from '@quik/passport';
import { Decorators, QRoute } from '@quik/http';

@Decorators.Route.Route('/me')
export class MeRoute extends QRoute {
  @Passport.Decorators.Bearer
  @Decorators.Endpoint.GET('/')
  async get() {
    return { ok: true };
  }
}

OAuth Provider Registration​

import { Passport } from '@quik/passport';
import { SecuritySchemeType } from '@quik/authorization';
import { Strategy as GoogleStrategy } from 'passport-google-oauth20';

Passport.Providers.register({
  name: 'google',
  strategy: GoogleStrategy,
  options: {
    clientID: process.env.GOOGLE_CLIENT_ID ?? '',
    clientSecret: process.env.GOOGLE_CLIENT_SECRET ?? '',
    callbackURL: '/auth/google/callback'
  },
  verify: async (accessToken, refreshToken, profile, done) => {
    done(null, { id: profile.id, email: profile.emails?.[0]?.value });
  },
  securityScheme: {
    type: SecuritySchemeType.OAUTH2,
    flows: {
      authorizationCode: {
        authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
        tokenUrl: 'https://oauth2.googleapis.com/token',
        scopes: {}
      }
    }
  }
});

Passkey API​

The package exports Passport.Passkey helpers:

  • createRegistrationOptions(input).
  • verifyRegistration(challengeId, response, request?).
  • createAuthenticationOptions(input?).
  • verifyAuthentication(challengeId, response, request?).
  • cleanupChallenges(now?).
  • setProvider(provider, name?), getProvider(name?), clearProviders().
  • setChallengeStore(store), getChallengeStore().
  • setCredentialStore(store), getCredentialStore().

Minimal Provider Example​

import { Passport } from '@quik/passport';

Passport.Passkey.setProvider({
  async verifyAuthentication(input) {
    // Validate WebAuthn assertion and resolve user.
    return { id: 'u1', email: 'user@example.com' } as any;
  },
  async verifyRegistration(input) {
    // Validate WebAuthn attestation.
    return true;
  }
});

Use The Passkey Strategy On Endpoints​

import { Passport } from '@quik/passport';
import { Decorators, QRoute } from '@quik/http';

@Decorators.Route.Route('/auth/passkey')
export class PasskeyRoute extends QRoute {
  @Passport.Decorators.Passkey
  @Decorators.Endpoint.POST('/verify')
  async verify() {
    return { ok: true };
  }
}

Credential Store Contract​

Passkey credentials can be backed by your own persistence by implementing IQPasskeyCredentialStore and registering it with:

import { Passport } from '@quik/passport';

Passport.Passkey.setCredentialStore(myCredentialStore);

When createAuthenticationOptions({ userId }) is called without allowCredentials, stored credentials for that user are used automatically.

API Reference​

Generated API documentation is available in the passport API section.