@authyon/server 0.2.0-beta.0 → 0.2.0-beta.1

package/dist/index.d.ts

@@ -1,3 +1,97 @@
+import { JSONWebKeySet, JWTPayload, JWSHeaderParameters } from 'jose';
+
+interface ClientRequestContext {
+    /** Real end-user IP, resolved only from infrastructure trusted by the application. */
+    clientIp?: string;
+}
+/** Rejects header injection and values that are not a single IPv4 or IPv6 address. */
+declare function normalizeClientIp(value: string): string;
+
+interface HttpAdapterRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: BodyInit | null;
+    signal: AbortSignal;
+}
+/** Transport contract accepted by both Authyon clients. */
+interface HttpAdapter {
+    request(request: HttpAdapterRequest): Promise<Response>;
+}
+type HttpLogEvent = {
+    type: "request";
+    method: string;
+    url: string;
+    timestamp: number;
+} | {
+    type: "response";
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    requestId?: string;
+    timestamp: number;
+} | {
+    type: "error";
+    method: string;
+    url: string;
+    errorName: string;
+    durationMs: number;
+    timestamp: number;
+};
+/** Receives sanitized HTTP lifecycle events. Headers, bodies and query values are never exposed. */
+type HttpLogger = (event: HttpLogEvent) => void;
+/**
+ * Mutable logging configuration. Change `enabled` at runtime to enable or disable logging
+ * without recreating the Authyon client.
+ */
+interface HttpLoggerOptions {
+    enabled: boolean;
+    logger?: HttpLogger;
+}
+/** Default adapter backed by the platform's Fetch API. */
+declare class FetchHttpAdapter implements HttpAdapter {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: typeof fetch);
+    request(request: HttpAdapterRequest): Promise<Response>;
+}
+/** Adds safe, configurable lifecycle logging to any HTTP adapter. */
+declare class LoggingHttpAdapter implements HttpAdapter {
+    private readonly adapter;
+    private readonly options;
+    constructor(adapter: HttpAdapter, options: HttpLoggerOptions);
+    request(request: HttpAdapterRequest): Promise<Response>;
+    private log;
+}
+
+interface PaginationOptions {
+    skip?: number;
+    take?: number;
+}
+interface Paged<T> {
+    data: T[];
+    perPage?: number;
+    pageSize: number;
+    total: number;
+    pages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+interface IntrospectResult {
+    active: boolean;
+    sub?: string;
+    username?: string | null;
+    email?: string | null;
+    roles?: string[] | null;
+    permissions?: string[];
+    client_id?: string;
+    scope?: string;
+    exp?: number;
+    iat?: number;
+    jti?: string;
+    token_type?: string;
+}
+
 /** GET/POST /env/tenants — confirmed against the live API. */
 interface Organization {
     id: string;
@@ -74,21 +168,6 @@ interface EnvironmentUser {
     /** JSON-encoded string. */
     customFields?: string;
 }
-/** POST /auth/introspect (RFC 7662) — confirmed against the live API. */
-interface IntrospectResult {
-    active: boolean;
-    sub?: string;
-    username?: string | null;
-    email?: string | null;
-    roles?: string[] | null;
-    permissions?: string[];
-    client_id?: string;
-    scope?: string;
-    exp?: number;
-    iat?: number;
-    jti?: string;
-    token_type?: string;
-}
 /**
  * POST /auth/validate — confirmed against the live API. The wire shape is
  * `{ valid, reason, profile }`, not `{ user, organization }` as the
@@ -202,21 +281,6 @@ type LoginActivity = AuditEvent;
  * Endpoints without `skip`/`take` params (e.g. `/env/tenants`) return a
  * bare array instead.
  */
-interface Page<T> {
-    data: T[];
-    /** Item count actually returned for this page. */
-    perPage?: number;
-    pageSize: number;
-    total: number;
-    pages: number;
-    hasNext: boolean;
-    hasPrev: boolean;
-}
-/** Pagination options accepted by list endpoints. */
-interface PageParams {
-    skip?: number;
-    take?: number;
-}
 /** OAuth 2.0 client-credentials pair minted in the Authyon console. */
 interface ClientCredentials {
     clientId: string;
@@ -257,18 +321,75 @@ interface AuthyonServerClientOptions {
     clientSecret?: string;
     /** API origin. Defaults to `https://api.authyon.com`. */
     baseUrl?: string;
-    /** Custom fetch implementation (useful for tests / edge runtimes). */
+    /** Allow an HTTP `baseUrl`. Intended only for explicitly trusted local development. */
+    allowInsecureHttp?: boolean;
+    /** Maximum duration of each HTTP request. Defaults to 15 seconds; set to `0` to disable. */
+    timeoutMs?: number;
+    /** Custom HTTP adapter for tracing, mocks or an alternative HTTP stack. */
+    httpAdapter?: HttpAdapter;
+    /** Safe HTTP lifecycle logging. Disabled unless this option is provided with `enabled: true`. */
+    httpLogger?: HttpLoggerOptions;
+    /** @deprecated Prefer `httpAdapter: new FetchHttpAdapter(customFetch)`. */
     fetch?: typeof fetch;
 }
 
-interface RequestOptions {
-    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-    body?: unknown;
-    query?: object;
-    headers?: Record<string, string>;
-    /** Attach the cached environment access token, minting one first if needed. */
-    envBearer?: boolean;
+type SafeJwtAlgorithm = "RS256" | "PS256" | "ES256" | "EdDSA";
+interface AuthyonJwtClaims extends JWTPayload {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    email?: string;
+    username?: string;
+    roles?: string[];
+    permissions?: string[];
+    scope?: string;
+}
+interface VerifiedAccessToken {
+    claims: AuthyonJwtClaims;
+    protectedHeader: JWSHeaderParameters;
+}
+interface JwksTokenVerifierOptions {
+    /** Exact trusted issuer from Authyon OpenID discovery. */
+    issuer: string;
+    /** Audience assigned to the API consuming this token. */
+    audience: string | string[];
+    /** Trusted HTTPS JWKS endpoint. Never derive this value from the token header. */
+    jwksUri?: string;
+    /** Static trusted keys for pinned or offline verification. */
+    jwks?: JSONWebKeySet;
+    algorithms?: readonly SafeJwtAlgorithm[];
+    acceptedTokenTypes?: readonly string[];
+    clockToleranceSeconds?: number;
+    maxTokenAgeSeconds?: number;
+    jwksTimeoutMs?: number;
+    jwksCacheMs?: number;
+    jwksCooldownMs?: number;
+}
+interface AuthyonJwksDiscoveryOptions extends Omit<JwksTokenVerifierOptions, "issuer" | "jwksUri" | "jwks"> {
+    /** Optional pin; discovery fails if Authyon advertises a different issuer. */
+    issuer?: string;
+    /** Override the client environment key used by the discovery endpoint. */
+    publishableKey?: string;
+}
+type TokenVerificationErrorCode = "token.invalid" | "token.expired" | "token.not_active" | "token.invalid_claims" | "token.invalid_signature" | "token.key_unavailable";
+declare class TokenVerificationError extends Error {
+    readonly code: TokenVerificationErrorCode;
+    constructor(code: TokenVerificationErrorCode, options?: {
+        cause?: unknown;
+    });
 }
+/** Secure, cached JWT signature and claims verifier backed by a trusted remote JWKS. */
+declare class JwksTokenVerifier {
+    private readonly options;
+    private readonly verifyKey;
+    private readonly algorithms;
+    private readonly acceptedTokenTypes;
+    constructor(options: JwksTokenVerifierOptions);
+    verifyAccessToken(token: string): Promise<VerifiedAccessToken>;
+}
+
 /**
  * Server-side Authyon client: environment/tenant administration (OAuth
  * client-credentials) plus access-token verification (publishable key).
@@ -279,10 +400,9 @@ declare class AuthyonServerClient {
     private readonly envKey?;
     private readonly clientId?;
     private readonly clientSecret?;
-    private readonly baseUrl;
-    private readonly fetchImpl;
-    private environmentToken;
-    private environmentTokenInFlight;
+    private readonly transport;
+    private readonly http;
+    private readonly environmentTokenProvider;
     constructor(options?: AuthyonServerClientOptions);
     private request;
     /** Mints (and caches) an environment access token from `clientId`/`clientSecret`. */
@@ -293,10 +413,12 @@ declare class AuthyonServerClient {
         /** GET /.well-known/openid-configuration — OIDC discovery document. */
         openidConfiguration: (publishableKey?: string) => Promise<OpenIdConfiguration>;
     };
+    /** Discovers Authyon's trusted issuer/JWKS and creates a cached local access-token verifier. */
+    createJwksTokenVerifier(options: AuthyonJwksDiscoveryOptions): Promise<JwksTokenVerifier>;
     /** POST /auth/introspect — lightweight token introspection (RFC 7662). */
-    introspect(token: string): Promise<IntrospectResult>;
+    introspect(token: string, context?: ClientRequestContext): Promise<IntrospectResult>;
     /** POST /auth/validate — recommended: cross-checks DB state, catches revocation immediately. */
-    validate(token: string): Promise<ValidateResult>;
+    validate(token: string, context?: ClientRequestContext): Promise<ValidateResult>;
     readonly environmentAuth: {
         /** POST /env/oauth/token — exchanges environment client credentials for an access token. */
         token: (credentials: ClientCredentials) => Promise<TokenResult>;
@@ -317,7 +439,7 @@ declare class AuthyonServerClient {
             /** GET /env/users — paginated list of users in the environment. */
             list: (params?: {
                 search?: string;
-            } & PageParams) => Promise<Page<EnvironmentUser>>;
+            } & PaginationOptions) => Promise<Paged<EnvironmentUser>>;
             /** POST /env/users — create a user in the environment; returns only the new id. */
             create: (input: CreateUserInput) => Promise<{
                 id: string;
@@ -372,7 +494,7 @@ declare class AuthyonServerClient {
                  * accepting `skip`/`take`), with the same shape
                  * `environment.users.list()` items have.
                  */
-                list: (tenantId: string, params?: PageParams) => Promise<EnvironmentUser[]>;
+                list: (tenantId: string, params?: PaginationOptions) => Promise<EnvironmentUser[]>;
                 /** POST /env/tenants/{tenantId}/members — add a member to a tenant. */
                 add: (tenantId: string, userId: string, roles?: string[]) => Promise<void>;
                 /** DELETE /env/tenants/{tenantId}/members/{userId} — remove a member from a tenant. */
@@ -423,9 +545,9 @@ declare class AuthyonServerClient {
         };
         audit: {
             /** GET /env/audit — paginated list of the environment's audit events. */
-            list: (params?: PageParams) => Promise<Page<AuditEvent>>;
+            list: (params?: PaginationOptions) => Promise<Paged<AuditEvent>>;
             /** GET /env/audit/login-activity — paginated login activity in the environment. */
-            loginActivity: (params?: PageParams) => Promise<Page<LoginActivity>>;
+            loginActivity: (params?: PaginationOptions) => Promise<Paged<LoginActivity>>;
         };
     };
     readonly permissions: {
@@ -435,7 +557,12 @@ declare class AuthyonServerClient {
         revoke: (userId: string, permission: string) => Promise<void>;
     };
     /** @internal used by {@link TenantScopedClient} to share the base URL/fetch/error handling. */
-    _requestAsTenant<T>(accessToken: string, path: string, options?: RequestOptions): Promise<T>;
+    _requestAsTenant<T>(accessToken: string, path: string, options?: {
+        method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        body?: unknown;
+        query?: object;
+        headers?: Record<string, string>;
+    }): Promise<T>;
 }
 /**
  * Client scoped to a single tenant's OAuth credentials — every call acts on
@@ -444,9 +571,7 @@ declare class AuthyonServerClient {
  */
 declare class TenantScopedClient {
     private readonly server;
-    private readonly credentials;
-    private token;
-    private tokenInFlight;
+    private readonly tokenProvider;
     constructor(server: AuthyonServerClient, credentials: ClientCredentials);
     private getAccessToken;
     private request;
@@ -460,7 +585,7 @@ declare class TenantScopedClient {
          * user records), since both are the "admin" member listing as opposed
          * to `/auth/tenants/{id}/members`'s paginated, lightweight one.
          */
-        list: (params?: PageParams) => Promise<EnvironmentUser[]>;
+        list: (params?: PaginationOptions) => Promise<EnvironmentUser[]>;
         /** POST /tenant/members — add a member to the token's tenant. */
         add: (userId: string, roles?: string[]) => Promise<void>;
         /** DELETE /tenant/members/{userId} — remove a member from the token's tenant. */
@@ -497,23 +622,180 @@ declare class TenantScopedClient {
 /** Convenience factory: `const authyon = createClient({ clientId, clientSecret })`. */
 declare function createClient(options?: AuthyonServerClientOptions): AuthyonServerClient;
 
-/**
- * Error thrown for any non-2xx Authyon API response.
- *
- * The API uses RFC 7807 problem+json: `{ title, status, detail, code }`.
- * Match on the machine-readable `code` (e.g. `user.email_taken`), never on `title`.
- */
+/** Builds a server client while keeping environment credentials grouped. */
+declare class AuthyonServerClientBuilder {
+    private readonly options;
+    withEnvironmentKey(envKey: string): this;
+    withEnvironmentCredentials(clientId: string, clientSecret: string): this;
+    withBaseUrl(baseUrl: string, allowInsecureHttp?: boolean): this;
+    withTimeout(timeoutMs: number): this;
+    withHttpAdapter(httpAdapter: HttpAdapter): this;
+    withHttpLogger(httpLogger: HttpLoggerOptions): this;
+    build(): AuthyonServerClient;
+}
+
+declare const ErrorCodes: {
+    readonly Unknown: "unknown";
+    readonly NetworkError: "request.network_error";
+    readonly Timeout: "request.timeout";
+    readonly SessionMalformed: "session.malformed";
+    readonly NotAuthenticated: "auth.not_authenticated";
+    readonly InvalidToken: "auth.invalid_token";
+    readonly MissingToken: "auth.missing_token";
+    readonly EmailTaken: "user.email_taken";
+    readonly PasswordWeak: "user.password_weak";
+    readonly PasswordPwned: "user.password_pwned";
+    readonly RateLimited: "rate_limited";
+};
+type KnownErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+type AuthyonErrorCategory = "network" | "timeout" | "authentication" | "authorization" | "validation" | "not_found" | "conflict" | "rate_limit" | "server" | "unknown";
+type AuthyonErrorAction = "retry" | "reauthenticate" | "request_access" | "fix_input" | "not_found" | "resolve_conflict" | "contact_support";
+interface AuthyonErrorInterpretation {
+    category: AuthyonErrorCategory;
+    action: AuthyonErrorAction;
+    retryable: boolean;
+    retryAfter?: number;
+    requestId?: string;
+}
+/** Shared RFC 7807 error implementation used by both public SDKs. */
 declare class AuthyonError extends Error {
     readonly status: number;
     readonly code: string;
     readonly title: string;
     readonly detail?: string;
+    readonly requestId?: string;
+    readonly retryAfter?: number;
+    readonly cause?: unknown;
     constructor(status: number, body: Partial<{
         title: string;
         detail: string;
         code: string;
-    }>);
+    }>, options?: {
+        requestId?: string;
+        retryAfter?: number;
+        cause?: unknown;
+    });
     is(code: string): boolean;
+    isAny(...codes: readonly string[]): boolean;
+    hasPrefix(prefix: string): boolean;
+    isStatus(...statuses: readonly number[]): boolean;
+    /** Stable interpretation for UI decisions, retries, telemetry and support flows. */
+    interpret(): AuthyonErrorInterpretation;
+    get category(): AuthyonErrorCategory;
+    get retryable(): boolean;
+    toJSON(): Record<string, unknown>;
+}
+
+type AbilitySubject = string | Record<string, unknown>;
+type AbilityConditions = Record<string, unknown>;
+interface AbilityRule {
+    action: string | string[];
+    subject: string | string[];
+    inverted?: boolean;
+    conditions?: AbilityConditions;
+    fields?: string[];
+    reason?: string;
+}
+interface AuthyonPermissionSource {
+    permissions?: readonly string[] | null;
+    roles?: readonly string[] | null;
+    /** OAuth scopes are also accepted and interpreted as Authyon permissions. */
+    scope?: string | null;
+}
+interface AuthyonAbilityOptions {
+    rules?: readonly AbilityRule[];
+    /** Rules added when the source contains a matching Authyon role. */
+    roleRules?: Readonly<Record<string, readonly AbilityRule[]>>;
+    roles?: readonly string[] | null;
+    detectSubjectType?: (subject: Record<string, unknown>) => string;
+}
+type AbilityEvent = "updated";
+type AbilityListener = (rules: readonly AbilityRule[]) => void;
+/** Isomorphic, deny-by-default authorization engine backed by Authyon permissions. */
+declare class AuthyonAbility {
+    private readonly detectSubjectType;
+    private currentRules;
+    private readonly listeners;
+    constructor(rules?: readonly AbilityRule[], detectSubjectType?: (subject: Record<string, unknown>) => string);
+    get rules(): readonly AbilityRule[];
+    can(action: string, subject: AbilitySubject, field?: string): boolean;
+    cannot(action: string, subject: AbilitySubject, field?: string): boolean;
+    rulesFor(action: string, subject: string): readonly AbilityRule[];
+    update(rules: readonly AbilityRule[]): void;
+    on(event: AbilityEvent, listener: AbilityListener): () => void;
+}
+/** Fluent rule builder with CASL-like `can` and `cannot` methods. */
+declare class AuthyonAbilityBuilder {
+    readonly rules: AbilityRule[];
+    can(action: string | string[], subject: string | string[], conditions?: AbilityConditions, fields?: string[]): this;
+    cannot(action: string | string[], subject: string | string[], conditions?: AbilityConditions, fields?: string[], reason?: string): this;
+    build(options?: Pick<AuthyonAbilityOptions, "detectSubjectType">): AuthyonAbility;
+}
+/** Creates an ability from Authyon permissions, OAuth scope and optional role rules. */
+declare function createAuthyonAbility(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AuthyonAbility;
+/** Converts Authyon's `subject:action` permission strings to authorization rules. */
+declare function createAuthyonRules(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AbilityRule[];
+
+interface AbilityRequirement {
+    action: string;
+    subject: AbilitySubject;
+    field?: string;
+}
+interface AuthorizationContext {
+    token: string;
+    userId?: string;
+    ability: AuthyonAbility;
+    permissions: readonly string[];
+    roles: readonly string[];
+}
+interface AuthorizationOptions extends AuthyonAbilityOptions {
+    requirement?: AbilityRequirement;
+    /** Uses database-backed validation by default; introspection can be selected when desired. */
+    verification?: "validate" | "introspect" | "jwks";
+    /** Required for local JWKS verification. Create once and reuse its key cache. */
+    jwksVerifier?: JwksTokenVerifier;
+    /** Real end-user IP, obtained from trusted application infrastructure. */
+    clientIp?: string;
+}
+declare class AuthorizationError extends Error {
+    readonly status: 401 | 403 | 503;
+    readonly code: "authorization.unauthenticated" | "authorization.forbidden" | "authorization.unavailable";
+    constructor(status: 401 | 403 | 503, code: "authorization.unauthenticated" | "authorization.forbidden" | "authorization.unavailable", message: string);
+}
+/** Validates a bearer token and creates an Authyon-backed ability for server runtimes. */
+declare function authorizeToken(client: AuthyonServerClient, token: string, options?: AuthorizationOptions): Promise<AuthorizationContext>;
+/** Works with Web Request objects used by Next.js Route Handlers and other Fetch runtimes. */
+declare function authorizeRequest(client: AuthyonServerClient, request: Pick<Request, "headers">, options?: RequestAuthorizationOptions): Promise<AuthorizationContext>;
+interface RequestAuthorizationOptions extends AuthorizationOptions {
+    /** Platform-aware resolver. Only read headers that your trusted proxy overwrites. */
+    resolveClientIp?: (request: Pick<Request, "headers">) => string | undefined;
+}
+interface ExpressRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+    authyon?: AuthorizationContext;
+}
+interface ExpressResponseLike {
+    status(code: number): ExpressResponseLike;
+    json(body: unknown): unknown;
+}
+type ExpressNext = (error?: unknown) => void;
+interface ExpressAuthorizationMiddlewareOptions extends AuthorizationOptions {
+    /** Property assigned to the request. Defaults to `authyon`. */
+    requestProperty?: string;
+    /** Pass authorization errors to Express error middleware instead of writing a JSON response. */
+    passErrorsToNext?: boolean;
+    /** Trust Express's proxy-aware `request.ip`. Disabled by default. */
+    trustProxy?: boolean;
+    /** Overrides all built-in IP resolution; return only a trusted, single client IP. */
+    resolveClientIp?: (request: ExpressRequestLike) => string | undefined;
 }
+/** Dependency-free middleware compatible with Express and similar Connect frameworks. */
+declare function createExpressAuthorizationMiddleware(client: AuthyonServerClient, options?: ExpressAuthorizationMiddlewareOptions): (request: ExpressRequestLike & Record<string, unknown>, response: ExpressResponseLike, next: ExpressNext) => Promise<void>;
+/** Converts an authorization error into a Fetch Response suitable for Next.js. */
+declare function createAuthorizationErrorResponse(error: unknown): Response;
 
-export { type AuditEvent, AuthyonError, AuthyonServerClient, type AuthyonServerClientOptions, type ClientCredentials, type CreateOrganizationInput, type CreatePermissionInput, type CreateUserInput, type EnvironmentUser, type IntrospectResult, type JsonWebKeySet, type LoginActivity, type OpenIdConfiguration, type Organization, type Page, type PageParams, type Permission, type PermissionsByRole, type ReservedPermissions, type Role, type RoleGrant, type RoleInput, type RoleList, type RolePermissions, type TenantMembership, TenantScopedClient, type TokenResult, type UpdateOrganizationInput, type User, type ValidateResult, createClient };
+export { type AbilityConditions, type AbilityEvent, type AbilityListener, type AbilityRequirement, type AbilityRule, type AbilitySubject, type AuditEvent, type AuthorizationContext, AuthorizationError, type AuthorizationOptions, AuthyonAbility, AuthyonAbilityBuilder, type AuthyonAbilityOptions, AuthyonError, type AuthyonErrorAction, type AuthyonErrorCategory, type AuthyonErrorInterpretation, type AuthyonJwksDiscoveryOptions, type AuthyonJwtClaims, type AuthyonPermissionSource, AuthyonServerClient, AuthyonServerClientBuilder, type AuthyonServerClientOptions, type ClientCredentials, type ClientRequestContext, type CreateOrganizationInput, type CreatePermissionInput, type CreateUserInput, type EnvironmentUser, ErrorCodes, type ExpressAuthorizationMiddlewareOptions, type ExpressNext, type ExpressRequestLike, type ExpressResponseLike, FetchHttpAdapter, type HttpAdapter, type HttpAdapterRequest, type HttpLogEvent, type HttpLogger, type HttpLoggerOptions, type IntrospectResult, type JsonWebKeySet, JwksTokenVerifier, type JwksTokenVerifierOptions, type KnownErrorCode, LoggingHttpAdapter, type LoginActivity, type OpenIdConfiguration, type Organization, type Paged, type PaginationOptions, type Permission, type PermissionsByRole, type RequestAuthorizationOptions, type ReservedPermissions, type Role, type RoleGrant, type RoleInput, type RoleList, type RolePermissions, type SafeJwtAlgorithm, type TenantMembership, TenantScopedClient, type TokenResult, TokenVerificationError, type TokenVerificationErrorCode, type UpdateOrganizationInput, type User, type ValidateResult, type VerifiedAccessToken, authorizeRequest, authorizeToken, createAuthorizationErrorResponse, createAuthyonAbility, createAuthyonRules, createClient, createExpressAuthorizationMiddleware, normalizeClientIp };