SDK Reference
Private beta · TypeScript
The stable app-layer contract. One call chain:createFrauthy(config) →session(req) →can(action, resource) →boolean.
TypeScript
Published and supported as the primary SDK.
PublishedRust
An implementation exists alongside the TypeScript contract.
ExistsGo
A native Go implementation is planned.
PlannedPython
A native Python implementation is planned.
PlannedThis page is the canonical TypeScript reference for the private-beta application SDK.
Approved participants receive package coordinates, compatibility details, and access instructions through the private-beta channel. Public examples retain the API contract without exposing executable setup.
Canonical private-beta reference on this page.
An implementation exists, but a detailed public reference is not published. No dead route is exposed.
An implementation exists, but a detailed public reference is not published. No dead route is exposed.
An implementation exists, but a detailed public reference is not published. No dead route is exposed.
Package coordinates and setup instructions are provided only to approved private-beta participants.
Approved access
# Approved private-beta participants [PRIVATE_BETA_INSTALL_INSTRUCTIONS_REDACTED]
Two steps: configure a Frauthy instance, then guard routes with session and can.
frauthy.ts — Configuration
import { createFrauthy, resource } from "[PRIVATE_BETA_PACKAGE_COORDINATE_REDACTED]"; const portal = resource("portal", "gpfamily"); const frauthy = createFrauthy({ provider: { issuer: "https://login.mypeople.com", audience: "gpfamily-portal" }, store: { kind: "spicedb", endpoint: "https://spicedb.prod.example.com:8443", token: process.env.SPICEDB_TOKEN!, }, mapping: [{ claimField: "email_domain", match: { kind: "domain_equals", value: "mypeople.com" }, emit: { object: "domain:{domain}", relation: "member", subject: "user:{sub}" }, }], telemetry: { enabled: true, endpoint: "https://ingest.frauthy.cloud", apiKey: process.env.FRAUTHY_CLOUD_API_KEY, serviceName: "gpfamily-portal", }, });
server.ts — Request handler
app.get("/portal", async (req) => { const session = await frauthy.session(req); if (await session.can("access", portal)) { return render("portal"); } return new Response(null, { status: 403 }); });
The main factory function. Accepts a FrauthyConfig object and returns a configured Frauthy instance.
provider
Authentication. OIDC token verification supports issuer plus audience, or an explicit audience-validation opt-out.
store
Authorization. Configure the relationship store with kind, endpoint, optional token, and local-development TLS override.
mapping
MappingRule[] turns verified claims into relationship writes. Each rule defines claimField, match, and emit.
cookieName
The token-extraction cookie name. Defaults to frauthy_session.
telemetry
TelemetryConfig controls OTLP trace emission; see Section 05.
Returns a Frauthy instance with two methods:
Extract bearer/cookie token, verify via provider, run mapping rules, return a Session. Throws UnauthenticatedError on invalid or missing tokens.
Skip token extraction and build a session from pre-verified claims. Useful for S2S calls, tests, and local development.
// Return type interface Frauthy { session(req: Request): Promise<Session>; sessionFromClaims(claims: CanonicalClaims): Promise<Session>; }
The session object returned by frauthy.session(). Carries the verified identity and exposes permission checks against the relationship store.
Single permission check. Returns Promise<boolean>.
Negated check. Returns Promise<boolean>.
True only if all { action, resource } checks pass. Returns Promise<boolean>.
Which resources this subject can reach. Returns Promise<string[]>.
claims
CanonicalClaims — the complete verified identity claim set from the token.
sub
string — shorthand for claims.sub.
string | undefined — shorthand for claims.email.
emailVerified
boolean — shorthand for claims.emailVerified.
// Full Session interface interface Session { can(action: string, resource: Resource): Promise<boolean>; cannot(action: string, resource: Resource): Promise<boolean>; canAll(checks: PermissionCheck[]): Promise<boolean>; lookupResources(action: string, resourceType: string): Promise<string[]>; readonly claims: CanonicalClaims; readonly sub: string; readonly email: string | undefined; readonly emailVerified: boolean; }
OTLP-based trace emission. Zero overhead when disabled — no spans are created, no exporter is loaded.
enabled
boolean — defaults to false. This master switch keeps telemetry zero-overhead when disabled.
endpoint
string — defaults to http://localhost:4318, the OTLP/HTTP collector URL.
serviceName
string — defaults to frauthy-app and is reported in resource attributes.
apiKey
string — bearer token for OTLP export, required for Frauthy Cloud ingest.
headers
Record<string, string> — additional headers attached to OTLP export requests.
exporter
(payload) => void — custom export function replacing the built-in OTLP HTTP exporter.
// Full TelemetryConfig interface interface TelemetryConfig { enabled?: boolean; // default: false endpoint?: string; // default: "http://localhost:4318" serviceName?: string; // default: "frauthy-app" apiKey?: string; headers?: Record<string, string>; exporter?: (payload: unknown) => void; }
Three built-in guardrails that enforce safe defaults. These are not configurable — they are always active.
Mapping rules with email_domain or email as the claimField are silently skipped when emailVerified is false. Unverified email addresses never produce relationship writes.
SpiceDbStore rejects non-HTTPS endpoints unless the host is localhost. Pass allowInsecure: true in the store config for Docker-based local development.
StubProvider throws when NODE_ENV=production. Override with FRAUTHY_ALLOW_STUB=1 if you need stubs in a production-like environment.
Express, Hono, Next.js, and Astro adapters ship with the SDK. Each adapter wraps createFrauthy into the framework's native middleware or handler pattern.
Classic Express middleware. Attaches req.session on authenticated requests.
Hono middleware. Sets c.var.session in the context.
HOC and route-level guard for App Router server components and API routes.
Astro middleware. Injects session into Astro.locals.
Imports
// Express import { expressFrauthyMiddleware } from "[PRIVATE_BETA_PACKAGE_COORDINATE_REDACTED]"; // Hono import { honoFrauthyMiddleware } from "[PRIVATE_BETA_PACKAGE_COORDINATE_REDACTED]"; // Next.js import { withFrauthy, checkPermission } from "[PRIVATE_BETA_PACKAGE_COORDINATE_REDACTED]"; // Astro import { astroFrauthyMiddleware } from "[PRIVATE_BETA_PACKAGE_COORDINATE_REDACTED]";
SDK reference for the stable app-layer contract — authentication and fine-grained authorization in one call chain.