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

package/dist/index.d.cts

@@ -1,12 +1,5 @@
 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;
@@ -118,6 +111,8 @@ interface User {
     id: string;
     email: string;
     username?: string;
+    /** Environment-level roles from the database-validated user profile. */
+    roles?: string[];
     permissions?: string[];
 }
 interface RoleGrant {
@@ -278,9 +273,36 @@ type LoginActivity = AuditEvent;
 /**
  * Envelope every `skip`/`take`-paginated list endpoint returns, confirmed
  * live for `/env/users`, `/env/audit` and `/env/audit/login-activity`.
- * Endpoints without `skip`/`take` params (e.g. `/env/tenants`) return a
- * bare array instead.
+ * Endpoints without `skip`/`take` params return a bare array instead.
  */
+/** Tenant credential metadata. Listing never returns the secret. */
+interface TenantCredentialSummary {
+    id: string;
+    clientId: string;
+    description: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    expiresAt: string | null;
+    isActive: boolean;
+    permissions: string[];
+}
+/** Input for a tenant machine credential. Requires at least one explicit permission. */
+interface CreateTenantCredentialInput {
+    description: string;
+    /** Number of days until the tenant credential expires. Omit for no automatic expiration. */
+    lifetimeDays?: number | null;
+    permissions: string[];
+}
+/** The plaintext secret is returned only when the credential is issued. */
+interface TenantCredentialIssued {
+    credentialId: string;
+    clientId: string;
+    clientSecret: string;
+    createdAt: string;
+    expiresAt: string | null;
+    permissions: string[];
+}
 /** OAuth 2.0 client-credentials pair minted in the Authyon console. */
 interface ClientCredentials {
     clientId: string;
@@ -333,6 +355,252 @@ interface AuthyonServerClientOptions {
     fetch?: typeof fetch;
 }
 
+/** A token of the requested authentication plane, or a provider called for each request. */
+type AccessTokenSource = string | (() => string | Promise<string>);
+interface CredentialListOptions extends PaginationOptions {
+    search?: string;
+}
+/** scopes is an alias for permissions. Always supply an explicit, nonempty set. */
+type CredentialPermissionsInput = {
+    permissions: readonly string[];
+    scopes?: never;
+} | {
+    scopes: readonly string[];
+    permissions?: never;
+};
+type CreateCredentialInput = CredentialPermissionsInput & {
+    description?: string;
+    lifetimeDays?: number | null;
+};
+interface CredentialScope {
+    workspaceId: string;
+    environmentId: string;
+    tenantId?: string;
+}
+interface TenantManagementScope extends CredentialScope {
+    tenantId: string;
+}
+interface CredentialCreator {
+    id: string | null;
+    type: string;
+    displayName: string | null;
+}
+interface CredentialDetail extends TenantCredentialSummary {
+    createdBy: CredentialCreator | null;
+    updatedAt: string | null;
+    secretRotatedAt: string | null;
+    expiresAt: string | null;
+    ageSeconds: number;
+    /** Null while active; elapsed lifetime at revocation otherwise. */
+    lifetimeSeconds: number | null;
+    accessTokenLifetimeSeconds: number;
+}
+type WorkspaceRole = "admin" | "auditor";
+interface WorkspaceMember {
+    memberId: string | null;
+    userId: string;
+    email: string;
+    name: string;
+    role: string;
+    isOwner: boolean;
+    isSelf: boolean;
+    invitedByName: string | null;
+    joinedAt: string;
+    lastLoginAt: string | null;
+}
+interface WorkspaceInvite {
+    id: string;
+    email: string;
+    role: string;
+    invitedByName: string | null;
+    createdAt: string;
+    expiresAt: string;
+}
+interface WorkspaceTeam {
+    workspaceId: string;
+    workspaceName: string;
+    callerRole: string;
+    canManage: boolean;
+    members: WorkspaceMember[];
+    pendingInvites: WorkspaceInvite[];
+}
+interface InviteWorkspaceMemberInput {
+    email: string;
+    role: WorkspaceRole;
+}
+interface WorkspaceInviteIssued {
+    inviteId: string;
+    email: string;
+    role: string;
+    /** Sensitive bearer link returned at issuance. Do not log or persist in public storage. */
+    acceptUrl: string;
+    expiresAt: string;
+}
+interface WorkspaceInvitePreview {
+    workspaceName: string;
+    email: string;
+    role: string;
+    expiresAt: string;
+    requiresRegistration: boolean;
+}
+interface WorkspaceInviteAccepted {
+    workspaceId: string;
+    workspaceName: string;
+    role: string;
+    accountCreated: boolean;
+}
+interface AcceptWorkspaceInviteInput {
+    name?: string;
+    password?: string;
+}
+interface InviteTenantMemberInput {
+    email: string;
+    roles?: string[];
+}
+interface TenantMember {
+    userId: string;
+    email: string;
+    username: string;
+    roles: string[];
+    createdAt: string;
+    lastLoginAt: string | null;
+}
+type TenantMemberPage = Paged<TenantMember>;
+
+type QueryParams = object;
+
+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 HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface JsonRequestOptions {
+    method?: HttpMethod;
+    body?: unknown;
+    query?: QueryParams;
+    headers?: Record<string, string>;
+}
+
+type ManagementRequest = <T>(path: string, options?: JsonRequestOptions) => Promise<T>;
+
+/** Platform user administration. Never falls back to an environment machine token. */
+declare class PlatformScopedClient {
+    #private;
+    /** @hidden */
+    constructor(request: ManagementRequest, token: AccessTokenSource);
+    readonly credentials: {
+        list: (scope: CredentialScope, options?: CredentialListOptions) => Promise<Paged<TenantCredentialSummary>>;
+        get: (scope: CredentialScope, credentialId: string) => Promise<CredentialDetail>;
+        create: (scope: CredentialScope, input: CreateCredentialInput) => Promise<TenantCredentialIssued>;
+        updatePermissions: (scope: CredentialScope, credentialId: string, input: CredentialPermissionsInput) => Promise<void>;
+        updateScopes: (scope: CredentialScope, credentialId: string, scopes: readonly string[]) => Promise<void>;
+        /** Returns a new secret once. API may require an explicit step-up first. */
+        rotate: (scope: CredentialScope, credentialId: string) => Promise<TenantCredentialIssued>;
+        revoke: (scope: CredentialScope, credentialId: string) => Promise<void>;
+    };
+    readonly workspaces: {
+        team: (workspaceId: string) => Promise<WorkspaceTeam>;
+        members: {
+            invite: (workspaceId: string, input: InviteWorkspaceMemberInput) => Promise<WorkspaceInviteIssued>;
+            /** memberId comes from team.members; it is not the platform userId. */
+            remove: (workspaceId: string, memberId: string) => Promise<void>;
+            changeRole: (workspaceId: string, memberId: string, role: WorkspaceRole) => Promise<void>;
+        };
+        invites: {
+            create: (workspaceId: string, input: InviteWorkspaceMemberInput) => Promise<WorkspaceInviteIssued>;
+            revoke: (workspaceId: string, inviteId: string) => Promise<void>;
+        };
+    };
+    readonly tenants: {
+        members: {
+            list: (scope: TenantManagementScope, options?: PaginationOptions) => Promise<EnvironmentUser[]>;
+            add: (scope: TenantManagementScope, userId: string, roles?: string[]) => Promise<void>;
+            remove: (scope: TenantManagementScope, userId: string) => Promise<void>;
+        };
+    };
+    readonly auth: {
+        /** Explicitly confirms the current platform session; passwords are not retained. */
+        stepUp: (currentPassword: string) => Promise<void>;
+    };
+}
+/** End-user operations require a user token and the environment publishable key. */
+declare class UserScopedClient {
+    #private;
+    /** @hidden */
+    constructor(request: ManagementRequest, token: AccessTokenSource);
+    readonly tenants: {
+        members: {
+            list: (tenantId: string, options?: PaginationOptions) => Promise<TenantMemberPage>;
+            /** Adds an existing environment user by email; does not send an invitation email. */
+            invite: (tenantId: string, input: InviteTenantMemberInput) => Promise<TenantMember>;
+            remove: (tenantId: string, userId: string) => Promise<void>;
+        };
+    };
+}
+/** Anonymous invite endpoints: the invitation token itself authorizes these requests. */
+declare class WorkspaceInvitesClient {
+    #private;
+    /** @hidden */
+    constructor(request: ManagementRequest);
+    preview(token: string): Promise<WorkspaceInvitePreview>;
+    accept(token: string, input?: AcceptWorkspaceInviteInput): Promise<WorkspaceInviteAccepted>;
+}
+
+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;
+
 type SafeJwtAlgorithm = "RS256" | "PS256" | "ES256" | "EdDSA";
 interface AuthyonJwtClaims extends JWTPayload {
     sub: string;
@@ -397,9 +665,9 @@ declare class JwksTokenVerifier {
  * server.
  */
 declare class AuthyonServerClient {
+    #private;
     private readonly envKey?;
     private readonly clientId?;
-    private readonly clientSecret?;
     private readonly transport;
     private readonly http;
     private readonly environmentTokenProvider;
@@ -434,6 +702,11 @@ declare class AuthyonServerClient {
      * "the token's tenant" rather than one you pass by id.
      */
     tenant(credentials: ClientCredentials): TenantScopedClient;
+    /** Uses only the supplied platform-user access token. */
+    platform(token: AccessTokenSource): PlatformScopedClient;
+    /** Uses an end-user token; the configured environment key selects the environment. */
+    user(token: AccessTokenSource): UserScopedClient;
+    readonly workspaceInvites: WorkspaceInvitesClient;
     readonly environment: {
         users: {
             /** GET /env/users — paginated list of users in the environment. */
@@ -476,8 +749,24 @@ declare class AuthyonServerClient {
             removeTenant: (userId: string, tenantId: string) => Promise<void>;
         };
         tenants: {
-            /** GET /env/tenants — list tenants in the environment. */
-            list: () => Promise<Organization[]>;
+            credentials: {
+                /** GET /env/tenants/{tenantId}/credentials. Returns metadata only, including revoked credentials. */
+                list: (tenantId: string) => Promise<TenantCredentialSummary[]>;
+                /** Paginated searchable listing. Prefer this over loading every credential. */
+                listPage: (tenantId: string, options?: CredentialListOptions) => Promise<Paged<TenantCredentialSummary>>;
+                get: (tenantId: string, credentialId: string) => Promise<CredentialDetail>;
+                /** Explicit scopes/permissions; only issuance returns the client secret. */
+                create: (tenantId: string, input: CreateTenantCredentialInput | CreateCredentialInput) => Promise<TenantCredentialIssued>;
+                /** Returns a new secret once while keeping the same client id. */
+                rotate: (tenantId: string, credentialId: string) => Promise<TenantCredentialIssued>;
+                updatePermissions: (tenantId: string, credentialId: string, input: CredentialPermissionsInput) => Promise<void>;
+                updateScopes: (tenantId: string, credentialId: string, scopes: readonly string[]) => Promise<void>;
+                revoke: (tenantId: string, credentialId: string) => Promise<void>;
+            };
+            /** GET /env/tenants — paginated, searchable list of tenants in the environment. */
+            list: (params?: {
+                search?: string;
+            } & PaginationOptions) => Promise<Paged<Organization>>;
             /** POST /env/tenants — create a tenant in the environment. */
             create: (input: CreateOrganizationInput) => Promise<Organization>;
             /** GET /env/tenants/{tenantId} — fetch a tenant by id. */
@@ -624,7 +913,7 @@ declare function createClient(options?: AuthyonServerClientOptions): AuthyonServ
 
 /** Builds a server client while keeping environment credentials grouped. */
 declare class AuthyonServerClientBuilder {
-    private readonly options;
+    #private;
     withEnvironmentKey(envKey: string): this;
     withEnvironmentCredentials(clientId: string, clientSecret: string): this;
     withBaseUrl(baseUrl: string, allowInsecureHttp?: boolean): this;
@@ -634,58 +923,6 @@ declare class AuthyonServerClientBuilder {
     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 {
@@ -733,6 +970,8 @@ declare class AuthyonAbilityBuilder {
 }
 /** Creates an ability from Authyon permissions, OAuth scope and optional role rules. */
 declare function createAuthyonAbility(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AuthyonAbility;
+/** Checks an Authyon permission string using the same wildcard rules as an ability. */
+declare function hasPermission(source: AuthyonPermissionSource | readonly string[], requiredPermission: string): boolean;
 /** Converts Authyon's `subject:action` permission strings to authorization rules. */
 declare function createAuthyonRules(source?: AuthyonPermissionSource, options?: AuthyonAbilityOptions): AbilityRule[];
 
@@ -798,4 +1037,4 @@ declare function createExpressAuthorizationMiddleware(client: AuthyonServerClien
 /** Converts an authorization error into a Fetch Response suitable for Next.js. */
 declare function createAuthorizationErrorResponse(error: unknown): Response;
 
-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 };
+export { type AbilityConditions, type AbilityEvent, type AbilityListener, type AbilityRequirement, type AbilityRule, type AbilitySubject, type AcceptWorkspaceInviteInput, type AccessTokenSource, 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 CreateCredentialInput, type CreateOrganizationInput, type CreatePermissionInput, type CreateTenantCredentialInput, type CreateUserInput, type CredentialCreator, type CredentialDetail, type CredentialListOptions, type CredentialPermissionsInput, type CredentialScope, 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 InviteTenantMemberInput, type InviteWorkspaceMemberInput, type JsonWebKeySet, JwksTokenVerifier, type JwksTokenVerifierOptions, type KnownErrorCode, LoggingHttpAdapter, type LoginActivity, type OpenIdConfiguration, type Organization, type Paged, type PaginationOptions, type Permission, type PermissionsByRole, PlatformScopedClient, type RequestAuthorizationOptions, type ReservedPermissions, type Role, type RoleGrant, type RoleInput, type RoleList, type RolePermissions, type SafeJwtAlgorithm, type TenantCredentialIssued, type TenantCredentialSummary, type TenantManagementScope, type TenantMember, type TenantMemberPage, type TenantMembership, TenantScopedClient, type TokenResult, TokenVerificationError, type TokenVerificationErrorCode, type UpdateOrganizationInput, type User, UserScopedClient, type ValidateResult, type VerifiedAccessToken, type WorkspaceInvite, type WorkspaceInviteAccepted, type WorkspaceInviteIssued, type WorkspaceInvitePreview, WorkspaceInvitesClient, type WorkspaceMember, type WorkspaceRole, type WorkspaceTeam, authorizeRequest, authorizeToken, createAuthorizationErrorResponse, createAuthyonAbility, createAuthyonRules, createClient, createExpressAuthorizationMiddleware, hasPermission, normalizeClientIp };