@openknot-ts/auth0-actor
v0.0.6-preview
Published
Optional Auth0 verified-identity mapping.
Readme
@openknot-ts/auth0-actor
Verifies Auth0 access tokens and maps their claims to the application's actor, independently of any transport. It includes jose and configures JWT verification and JWKS discovery; applications supply the issuer, audience and mapActor.
Usage
import { provideAuth0 } from "@openknot-ts/auth0-actor/wire";
import { config } from "@openknot-ts/wire";
import { z } from "zod";
const settings = config({
AUTH0_ISSUER: z.url(),
AUTH0_AUDIENCE: z.string().min(1),
});
const identity = provideAuth0({
requirements: { settings },
factory: ({ settings }) => ({
issuer: settings.AUTH0_ISSUER,
audience: settings.AUTH0_AUDIENCE,
mapActor: (claims) => ({ userId: claims.sub }),
}),
});API
| Entry | Export | Description |
| --- | --- | --- |
| @openknot-ts/auth0-actor | auth0Resolver({ issuer, audience, mapActor, jwks?, verification? }) | An actor resolver, usable without Wire. |
| @openknot-ts/auth0-actor/wire | provideAuth0({ requirements?, factory }) | Provides Flow's executionActorResolver when its declared settings are available. |
jwkstakes jose'sRemoteJWKSetOptions: timeouts, headers, caching,customFetch.verificationtakes native tuning such as clock tolerance, subject, maximum age and extra required claims. It cannot remove the Auth0 contract.
Verification
- One remote key set per application, at the issuer's
/.well-known/jwks.json; jose owns fetching, caching and refresh. - Tokens must be RS256, match the issuer and audience, have a valid
expand a non-emptysub, and satisfynbfwhen present. Only verified claims reachmapActor, which may be async. - Invalid tokens, claims and unknown keys produce
ActorAuthenticationError. JWKS network failures, malformed key sets and mapping failures keep their own identity. - Raw tokens never reach the actor or telemetry. Business facts such as an event's
createdBybelong in the event, not in a restored token.
Transports
tRPC uses this module through trpcAuthentication from @openknot-ts/trpc-context/wire, or @openknot-ts/auth0-authentication builds the middleware from the same options. Another RPC calls auth0Resolver or the resolved executionActorResolver in its own context or middleware and passes the actor to Flow.
Tests
pnpm --filter @openknot-ts/auth0-actor test uses real signatures and local JWKS servers: claims, algorithms, unknown keys, caching, infrastructure failures, mapping, cancellation and conditional Wire composition, without an Auth0 tenant.
