@adonis-agora/authkit-server 0.90.2 → 1.0.0-rc.1

package/build/src/host/screen_props.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Props of every screen authkit-server renders through `cfg.render` — what an
+ * `inertiaRenderer` page (or a custom renderer) receives for each view.
+ *
+ * `AuthkitScreenProps['<view>']` is the shape a page gets, `messages` included
+ * (the renderer adds it). The controllers call `cfg.render` with
+ * {@link ScreenRenderProps} (the same shape without `messages`), and `render` is
+ * typed per view, so a controller that drifts from these types fails the
+ * package's `tsc`.
+ */
+import type { OrgInvitation, OrgMember, OrgSummary } from '../accounts/account_store.js';
+import type { PatRecord } from '../pat/pat_store.js';
+import type { AccountConfirmProps, AccountEmailConfirmedProps, AccountLoginProps, AccountMfaProps, AccountSecurityProps } from './account_screen_props.js';
+import type { BotProtectionWidget } from './bot_protection.js';
+import type { ClientBrand } from './branding.js';
+import type { CustomMfaDescriptor } from './custom_mfa.js';
+import type { AuthMessages } from './i18n.js';
+import type { LastLoginMethod } from './last_login_method.js';
+import type { MagicChannelProp } from './login_channel.js';
+import type { ResolvedAuthMethods, ResolvedOrganizationsPolicySetting } from './runtime_toggles.js';
+/** What every screen receives from the renderer. */
+interface WithMessages {
+    /** The i18n catalog for the request's locale (added by the renderer). */
+    messages: AuthMessages;
+}
+/** The account a login step is about (step 2+), or `null`. */
+export interface LoginAccount {
+    fullName: string | null;
+    globalRoles: string[];
+}
+/**
+ * `login` — the OIDC interaction's login screen. `step` drives the sub-view:
+ * `identifier` (ask for the e-mail), `password`, or `password_expired`.
+ */
+export interface LoginProps extends WithMessages {
+    uid: string;
+    csrfToken: string;
+    brand?: ClientBrand;
+    step?: 'identifier' | 'password' | 'password_expired';
+    email?: string;
+    account?: LoginAccount | null;
+    error?: string | null;
+    /** `true` shows the link to sign up. */
+    registrationEnabled?: boolean;
+    /** Login methods allowed now (global settings × the account's preference). */
+    authMethods?: ResolvedAuthMethods;
+    magicLinkAvailable?: boolean;
+    otpEnabled?: boolean;
+    /** The method this device signed in with last time, for the "last used" badge. */
+    lastUsedLoginMethod?: LastLoginMethod;
+    passkeyFirstAvailable?: boolean;
+    botProtection?: BotProtectionWidget;
+    rememberEnabled?: boolean;
+    rememberDays?: number;
+    /** `true` after a magic link / code was sent. */
+    magicLinkSent?: boolean;
+    /** Which part of the "sent" state to show; `none` hides both. */
+    magicChannel?: MagicChannelProp | 'none';
+    /** Error of the one-time code field. */
+    otpError?: string;
+}
+/** `signup` — the interaction's registration screen. */
+export interface SignupProps extends WithMessages {
+    uid: string;
+    csrfToken: string;
+    brand?: ClientBrand;
+    error?: string;
+    registrationDisabled?: boolean;
+    registrationDisabledMessage?: string;
+    /** `true` when signup sends a magic link instead of asking for a password. */
+    passwordlessSignup?: boolean;
+    botProtection?: BotProtectionWidget;
+    /** `true` after the passwordless signup link was sent. */
+    magicLinkSent?: boolean;
+    otpEnabled?: boolean;
+}
+/** `forgot` — request a password reset e-mail. */
+export interface ForgotProps extends WithMessages {
+    csrfToken: string;
+    error?: string;
+    botProtection?: BotProtectionWidget;
+    /** `true` after the e-mail was sent. */
+    sent?: boolean;
+}
+/** `reset` — choose a new password from the e-mailed link. */
+export interface ResetProps extends WithMessages {
+    token: string;
+    csrfToken: string;
+    error?: string;
+    /** `true` once the password was changed. */
+    done?: boolean;
+}
+/** `verify-email` — result of the e-mail verification link. */
+export interface VerifyEmailProps extends WithMessages {
+    verified: boolean;
+}
+/** A host-registered second factor, as the `mfa-challenge` screen lists it. */
+export type MfaChallengeCustomMethod = CustomMfaDescriptor & {
+    beginUrl: string;
+    verifyUrl: string;
+    started: boolean;
+};
+/** `mfa-challenge` — the second factor of a login. */
+export interface MfaChallengeProps extends WithMessages {
+    uid: string;
+    csrfToken: string;
+    brand?: ClientBrand;
+    error?: string;
+    totpAvailable?: boolean;
+    passkeyAvailable?: boolean;
+    /** MFA is required but the account has no factor enrolled. */
+    noEnrollment?: boolean;
+    trustedDevicesEnabled?: boolean;
+    trustedDeviceDays?: number;
+    /** Too many wrong codes: the code field is locked for now. */
+    otpLocked?: boolean;
+    customMfaMethods?: MfaChallengeCustomMethod[];
+    completedMfaMethods?: string[];
+    requiredMfaFactors?: number;
+}
+/** A scope on the consent screen. */
+export interface ConsentScope {
+    id: string;
+    label: string;
+}
+/**
+ * The authorization request behind a consent, as the provider parsed it. Only
+ * `client_id` is always there: device-flow and CIBA requests carry no
+ * `redirect_uri` / `response_type`, and plain OAuth requests may omit `scope`.
+ * Every other request parameter (`audience`, `resource`, `claims`, …) keeps its
+ * raw value under its own name.
+ */
+export type ConsentRequestParams = {
+    client_id: string;
+    redirect_uri?: string;
+    response_type?: string;
+    scope?: string;
+    state?: string;
+    prompt?: string;
+    nonce?: string;
+    code_challenge?: string;
+    code_challenge_method?: string;
+} & Record<string, unknown>;
+/** `consent` — the user grants the client the requested scopes. */
+export interface ConsentProps extends WithMessages {
+    uid: string;
+    csrfToken: string;
+    brand?: ClientBrand;
+    /** The authorization request parameters. */
+    params: ConsentRequestParams;
+    /** The client's registered `client_name`, or its `client_id`. */
+    clientName: string;
+    /** `clientName`, HTML-escaped (Edge raw output). */
+    clientNameHtml: string;
+    scopes: ConsentScope[];
+}
+/** `maintenance` — maintenance mode is on. */
+export interface MaintenanceProps extends WithMessages {
+    uid?: string;
+    csrfToken: string;
+    brand?: ClientBrand;
+    message: string;
+    /** Admins may still sign in. */
+    adminLoginAllowed?: boolean;
+    adminLoginNote?: string;
+}
+/** `otp-unlock` — result of the "unlock my code login" link. */
+export interface OtpUnlockProps extends WithMessages {
+    ok: boolean;
+    expired?: boolean;
+}
+/** `session-expired` — the interaction expired or was lost. */
+export interface SessionExpiredProps extends WithMessages {
+    /** Where the "sign in again" button goes (`interactionRecovery.redirectTo`). */
+    loginUrl: string;
+    brand?: ClientBrand;
+}
+/** `throttled` — the request hit a rate limit. */
+export interface ThrottledProps extends WithMessages {
+    brand?: ClientBrand;
+    /** Seconds until a retry is allowed, or `null` when unknown. */
+    retryAfter: number | null;
+    retryUrl: string;
+}
+/** The agent asking for access, on `agents/consent`. */
+export interface AgentConsentRequest {
+    /** Device-flow user code, when the agent uses it. */
+    userCode?: string;
+    agentName: string | null;
+    agentOrigin: string | null;
+    logoUri?: string | null;
+    scopes: Array<{
+        id: string;
+        description: string;
+    }>;
+    /** Extra hidden form fields to send back. */
+    hidden?: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/** `agents/consent` — the user approves a personal agent's request. */
+export interface AgentsConsentProps extends WithMessages {
+    csrfToken: string;
+    /** The form's POST target. */
+    action: string;
+    /** `null` while the user still has to enter a user code. */
+    request: AgentConsentRequest | null;
+    account: {
+        email: string | null;
+    } | null;
+    /** i18n key of the error to show, or `null`. */
+    error: string | null;
+}
+/** `agents/done` — outcome of a personal agent consent. */
+export interface AgentsDoneProps extends WithMessages {
+    status: 'approved' | 'denied' | 'expired' | 'invalid';
+    agentName: string | null;
+    scopes: Array<{
+        id: string;
+        description: string;
+    }>;
+}
+/** `account/apps` — apps and personal agents with access to the account. */
+export interface AccountAppsProps extends WithMessages {
+    csrfToken: string;
+    supported: boolean;
+    /** Personal agents with a delegation, or `null` when the feature is off. */
+    agents: Array<{
+        id: string;
+        name: string;
+        scopes: Array<{
+            id: string;
+            description: string;
+        }>;
+    }> | null;
+    /** Flash with the revoked app, or `null`. */
+    revoked: string | null;
+    apps: Array<{
+        clientId: string;
+        name: string;
+        /** The client's registered `logo_uri`, or `null`. */
+        logoUrl: string | null;
+        accessTokens: number;
+        refreshTokens: number;
+    }>;
+}
+/** `account/tokens` — personal access tokens. */
+export interface AccountTokensProps extends WithMessages {
+    csrfToken: string;
+    /** The token just created, shown once, or `null`. */
+    createdToken: string | null;
+    tokens: Array<Pick<PatRecord, 'id' | 'name' | 'scopes' | 'audience' | 'lastUsedAt' | 'createdAt'>>;
+}
+/** An organization on `account/orgs`. */
+export type AccountOrg = OrgSummary & {
+    role: string;
+    members: OrgMember[];
+    canManage: boolean;
+    isActive: boolean;
+};
+/**
+ * `account/orgs` — the user's organizations. With `subview: 'accept-invitation'`
+ * it is the invitation acceptance screen (`invitation`, `token`).
+ */
+export interface AccountOrgsProps extends WithMessages {
+    csrfToken: string;
+    supported?: boolean;
+    orgs?: AccountOrg[];
+    pendingInvitations?: Array<OrgInvitation & {
+        orgName: string;
+    }>;
+    allowSelfCreate?: ResolvedOrganizationsPolicySetting['allowSelfCreate'];
+    availableRoles?: ResolvedOrganizationsPolicySetting['roles'];
+    subview?: 'accept-invitation';
+    invitation?: OrgInvitation | null;
+    token?: string;
+}
+/** Props of every screen, by view name. */
+export interface AuthkitScreenProps {
+    login: LoginProps;
+    signup: SignupProps;
+    consent: ConsentProps;
+    forgot: ForgotProps;
+    reset: ResetProps;
+    'verify-email': VerifyEmailProps;
+    'mfa-challenge': MfaChallengeProps;
+    'otp-unlock': OtpUnlockProps;
+    maintenance: MaintenanceProps;
+    'session-expired': SessionExpiredProps;
+    throttled: ThrottledProps;
+    'agents/consent': AgentsConsentProps;
+    'agents/done': AgentsDoneProps;
+    'account/login': AccountLoginProps;
+    'account/tokens': AccountTokensProps;
+    'account/mfa': AccountMfaProps;
+    'account/security': AccountSecurityProps;
+    'account/apps': AccountAppsProps;
+    'account/orgs': AccountOrgsProps;
+    'account/confirm': AccountConfirmProps;
+    'account/email-confirmed': AccountEmailConfirmedProps;
+}
+/** Every screen authkit-server renders. */
+export type AuthkitScreen = keyof AuthkitScreenProps;
+/** What a controller hands `cfg.render` for a view: the page props without `messages`. */
+export type ScreenRenderProps<View extends AuthkitScreen> = Omit<AuthkitScreenProps[View], 'messages'>;
+/** `cfg.render`, typed per view. */
+export type AuthkitScreenRenderer = <View extends AuthkitScreen>(ctx: import('@adonisjs/core/http').HttpContext, view: View, props: ScreenRenderProps<View>) => unknown;
+export {};

package/build/src/host/screen_props.js

@@ -0,0 +1,11 @@
+/**
+ * Props of every screen authkit-server renders through `cfg.render` — what an
+ * `inertiaRenderer` page (or a custom renderer) receives for each view.
+ *
+ * `AuthkitScreenProps['<view>']` is the shape a page gets, `messages` included
+ * (the renderer adds it). The controllers call `cfg.render` with
+ * {@link ScreenRenderProps} (the same shape without `messages`), and `render` is
+ * typed per view, so a controller that drifts from these types fails the
+ * package's `tsc`.
+ */
+export {};

package/build/src/host/sudo_mode.d.ts

@@ -68,8 +68,8 @@ export declare const SUDO_SESSION_KEY = "authkit_sudo_at";
  * número e isso é contratual — está pinado em
  * `tests/host/account_confirm_controller.spec.ts` com `assert.isNumber`. Então
  * a vinculação é ADITIVA, em vez de mudar a forma do valor pinado para
- * `{ at, accountId }`. Bônus: as assinaturas públicas de `markSudo` /
- * `isSudoActive` (exportadas em `index.ts`) ficam intactas.
+ * `{ at, accountId }`. Bônus: a assinatura pública de `isSudoActive`
+ * (exportada em `index.ts`) fica intacta.
  */
 export declare const SUDO_ACCOUNT_SESSION_KEY = "authkit_sudo_account";
 /**
@@ -81,15 +81,9 @@ export declare const SUDO_ACCOUNT_SESSION_KEY = "authkit_sudo_account";
  * herdando o dono antigo. O resultado é uma marca órfã, que `isSudoActive`
  * recusa (fail-closed).
  *
- * @deprecated Para conceder sudo, use `completeSudo(sudoContextFrom(ctx), id)`.
- * `markSudo` grava a marca e nada mais: não registra o audit `sudo.confirmed`,
- * não lembra o método usado e não redireciona para o `return_to`. Um host que a
- * chame direto — o caminho natural no callback de `oidcStepUp`, antes de
- * `completeSudo` ser público — concede privilégio sem deixar rastro nenhum.
- * Continua exportada porque o login primário do próprio pacote a usa (ver o
- * CHANGELOG desta versão) e porque removê-la seria breaking; o uso legítimo
- * restante é ler/limpar a marca em fluxos que não são confirmação de
- * identidade.
+ * Interno: o único caminho público para conceder sudo é
+ * `completeSudo(sudoContextFrom(ctx), id)`, que além da marca registra o audit
+ * `sudo.confirmed`, lembra o método usado e redireciona para o `return_to`.
  */
 export declare function markSudo(ctx: HttpContext): void;
 /**

package/build/src/host/sudo_mode.js

@@ -87,8 +87,8 @@ export const SUDO_SESSION_KEY = 'authkit_sudo_at';
  * número e isso é contratual — está pinado em
  * `tests/host/account_confirm_controller.spec.ts` com `assert.isNumber`. Então
  * a vinculação é ADITIVA, em vez de mudar a forma do valor pinado para
- * `{ at, accountId }`. Bônus: as assinaturas públicas de `markSudo` /
- * `isSudoActive` (exportadas em `index.ts`) ficam intactas.
+ * `{ at, accountId }`. Bônus: a assinatura pública de `isSudoActive`
+ * (exportada em `index.ts`) fica intacta.
  */
 export const SUDO_ACCOUNT_SESSION_KEY = 'authkit_sudo_account';
 /**
@@ -100,15 +100,9 @@ export const SUDO_ACCOUNT_SESSION_KEY = 'authkit_sudo_account';
  * herdando o dono antigo. O resultado é uma marca órfã, que `isSudoActive`
  * recusa (fail-closed).
  *
- * @deprecated Para conceder sudo, use `completeSudo(sudoContextFrom(ctx), id)`.
- * `markSudo` grava a marca e nada mais: não registra o audit `sudo.confirmed`,
- * não lembra o método usado e não redireciona para o `return_to`. Um host que a
- * chame direto — o caminho natural no callback de `oidcStepUp`, antes de
- * `completeSudo` ser público — concede privilégio sem deixar rastro nenhum.
- * Continua exportada porque o login primário do próprio pacote a usa (ver o
- * CHANGELOG desta versão) e porque removê-la seria breaking; o uso legítimo
- * restante é ler/limpar a marca em fluxos que não são confirmação de
- * identidade.
+ * Interno: o único caminho público para conceder sudo é
+ * `completeSudo(sudoContextFrom(ctx), id)`, que além da marca registra o audit
+ * `sudo.confirmed`, lembra o método usado e redireciona para o `return_to`.
  */
 export function markSudo(ctx) {
     const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);