@productcraft/auth 0.7.1 → 0.8.1

package/dist/index.d.cts

@@ -156,7 +156,7 @@ declare class AuthHttpError<TData = unknown> extends Error {
  */
 type AuditLogEntryDto = {
     /**
-     * @description Canonical action string (e.g. `app.member.removed`, `role.created`).
+     * @description Canonical action string (e.g. `app.member.removed`, `role.created`). Account deletions: `auth.account.deleted` (one row per account, written in the deleting transaction; `resource` is `account`, `resource_id` the deleted account id, `metadata` `{ via, username, email_domain, created_at, verified }` where `via` is `platform`, `platform_bulk`, `consumer_admin` or `self`, plus `selection` (`{ mode, filter? }`) on bulk rows) and `auth.account.expired_unverified` (the unverified-account expiry job).
      * @type string
      */
     action: string;
@@ -981,6 +981,48 @@ type EndUserInviteListResponseDto = {
  * Generated by Kubb (https://kubb.dev/).
  * Do not edit manually.
  */
+declare const botProtectionResponseDtoProviderEnum: {
+    readonly turnstile: "turnstile";
+    readonly hcaptcha: "hcaptcha";
+};
+type BotProtectionResponseDtoProviderEnumKey = (typeof botProtectionResponseDtoProviderEnum)[keyof typeof botProtectionResponseDtoProviderEnum];
+type BotProtectionResponseDto = {
+    /**
+     * @description Whether sign-up requires a verified token.
+     * @type boolean
+     */
+    enabled: boolean;
+    /**
+     * @description Hostnames a solved challenge must come from. Empty = any.
+     * @type array
+     */
+    expected_hostnames: string[];
+    /**
+     * @type string
+     */
+    provider: BotProtectionResponseDtoProviderEnumKey;
+    /**
+     * @description Last four characters of the stored secret, so you can tell which one it is. null when none is stored.
+     * @type string
+     */
+    secret_last4: string | null;
+    /**
+     * @description Whether a provider secret is stored. The secret itself is never returned.
+     * @type boolean
+     */
+    secret_set: boolean;
+    /**
+     * @description Public widget site key.
+     * @type string
+     */
+    site_key: string;
+};
+
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+
 declare const authConfigResponseDtoMfaEnum: {
     readonly optional: "optional";
     readonly required: "required";
@@ -1007,6 +1049,10 @@ type AuthConfigResponseDto = {
      * @type array
      */
     allowed_redirect_origins: string[];
+    /**
+     * @description Sign-up bot protection; null when not configured.
+     */
+    bot_protection: BotProtectionResponseDto | null;
     /**
      * @type boolean
      */
@@ -1071,6 +1117,18 @@ type AuthConfigResponseDto = {
      * @type boolean
      */
     signup_enabled: boolean;
+    /**
+     * @description When true, sign-up requires a Platform API Key from this app\'s workspace (anonymous sign-ups get 401).
+     * @type boolean
+     */
+    signup_requires_pak: boolean;
+    /**
+     * @description Days an account may keep an unverified primary email before it is deleted. null = never.
+     * @minLength 1
+     * @maxLength 90
+     * @type number
+     */
+    unverified_account_ttl_days: number | null;
 };
 
 /**
@@ -1133,6 +1191,46 @@ type UpdateAppStatusDto = {
  * Generated by Kubb (https://kubb.dev/).
  * Do not edit manually.
  */
+declare const updateBotProtectionDtoProviderEnum: {
+    readonly turnstile: "turnstile";
+    readonly hcaptcha: "hcaptcha";
+};
+type UpdateBotProtectionDtoProviderEnumKey = (typeof updateBotProtectionDtoProviderEnum)[keyof typeof updateBotProtectionDtoProviderEnum];
+type UpdateBotProtectionDto = {
+    /**
+     * @description When true, every sign-up on this app must carry a `bot_protection_token` the provider accepts. Needs a stored secret. Takes effect within seconds.
+     * @type boolean | undefined
+     */
+    enabled?: boolean;
+    /**
+     * @description Hostnames the solved challenge must come from, as the provider reports them (exact match, no scheme, port or path). Empty (default) accepts any hostname the site key allows. Send null or [] to clear.
+     * @type array
+     */
+    expected_hostnames?: string[] | null;
+    /**
+     * @description Which CAPTCHA the app\'s sign-up form renders: Cloudflare Turnstile or hCaptcha. Required the first time the block is configured. Changing it without sending a new `secret` clears the stored secret, which belonged to the other provider.
+     * @type string | undefined
+     */
+    provider?: UpdateBotProtectionDtoProviderEnumKey;
+    /**
+     * @description The provider secret Auth verifies tokens with. WRITE-ONLY: no response ever returns it (GET shows `secret_set` and the last four characters). Send a string to store or replace it, null to clear it, or leave it out to keep the stored one. Stored encrypted.
+     * @maxLength 512
+     * @type string
+     */
+    secret?: string | null;
+    /**
+     * @description The public site key your sign-up page renders the widget with. Not a secret. Required the first time the block is configured.
+     * @maxLength 256
+     * @type string | undefined
+     */
+    site_key?: string;
+};
+
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+
 declare const updateAuthConfigDtoMfaEnum: {
     readonly optional: "optional";
     readonly required: "required";
@@ -1163,6 +1261,10 @@ type UpdateAuthConfigDto = {
      * @type array | undefined
      */
     allowed_redirect_origins?: string[];
+    /**
+     * @description Sign-up bot protection (Cloudflare Turnstile or hCaptcha). Fields you send are merged onto the stored block; send null to remove the block and its secret. While `enabled`, sign-up requires a `bot_protection_token` the provider accepts, checked before anything else, and fails closed (503) when the provider cannot be reached.
+     */
+    bot_protection?: UpdateBotProtectionDto | null;
     /**
      * @description When true, Consumer-API routes annotated with `@RequireAppPermission(perm)` enforce the requested perm against the EndUser\'s role-resolved permission set. When false (default), permission checks are bypassed — any valid token can call any annotated route. Flip on once you\'ve authored roles + permissions for this app and want them to actually mean something.
      * @type boolean | undefined
@@ -1253,6 +1355,18 @@ type UpdateAuthConfigDto = {
      * @type boolean | undefined
      */
     signup_enabled?: boolean;
+    /**
+     * @description When true, sign-up only works from your backend: every `POST /{app_slug}/v1/auth/signup` must carry a Platform API Key (`Authorization: Bearer pcft_live_…`) from this app\'s workspace whose policy allows `auth.signup.create` on this app. Anonymous sign-ups get 401. Use it when your own backend gates sign-ups (CAPTCHA, invite or payment checks). Independent of `bot_protection`; an app can use both. Turning it on for an app that has no workspace is refused with 409.
+     * @type boolean | undefined
+     */
+    signup_requires_pak?: boolean;
+    /**
+     * @description Delete accounts whose primary email is still unverified this many days after sign-up. Only self-sign-ups that never signed in after sign-up, hold no two-step factor, no verified contact and no social login qualify. Deletion is permanent, frees the email address and username, is audited as `auth.account.expired_unverified` and fires `user.deleted` with `reason: \"unverified_expired\"`. Send null to never delete. New apps start at 7; apps created before this setting existed start at null.
+     * @minLength 1
+     * @maxLength 90
+     * @type number
+     */
+    unverified_account_ttl_days?: number | null;
 };
 
 /**
@@ -1306,6 +1420,13 @@ type UpdateEndUserDto = {
      * @type string | undefined
      */
     email?: string;
+    /**
+     * @description Keys to merge into the end-user\'s metadata (shallow; a key set to null is removed; at most 8 KB stored). Set `app_active: true` to mark someone who uses your app: the unverified-account expiry never deletes an account carrying it.
+     * @type object | undefined
+     */
+    metadata?: {
+        [key: string]: any;
+    };
 };
 
 /**
@@ -2142,6 +2263,12 @@ type ConsumerAuthControllerSignin200 = ConsumerTokenResponseDto | ConsumerMfaCha
  * Do not edit manually.
  */
 type ConsumerSignupDto = {
+    /**
+     * @description The response token from the app\'s bot-protection widget (Cloudflare Turnstile or hCaptcha). Required when the app has bot protection switched on (`auth_config.bot_protection.enabled`); ignored otherwise. Auth verifies it with the provider before anything else about the sign-up is looked at. Tokens are single-use and expire after a few minutes, so render a fresh widget for every attempt. A backend that signs users up with a Platform API Key forwards the token its browser received.
+     * @maxLength 2048
+     * @type string | undefined
+     */
+    bot_protection_token?: string;
     /**
      * @description Optional display name shown back to the user.
      * @type string | undefined
@@ -2823,9 +2950,18 @@ interface VerifyOptions {
     /** Maximum token age — passed straight to jose. */
     maxTokenAge?: string | number;
 }
+/**
+ * True when the claims mark a refresh token: `token_use: "refresh"`
+ * (current shape) or `type: "refresh"` (older Auth tokens). Refresh
+ * tokens must never authenticate a request.
+ */
+declare function isRefreshToken(claims: Record<string, unknown> | null | undefined): boolean;
 /**
  * Verify an Auth-issued JWT against a JWKS resolver.
  *
+ * Refresh tokens are refused with `JwtRefreshTokenError` even when the
+ * signature, issuer and audience are valid.
+ *
  * @param token        The compact-form JWT (header.payload.signature)
  * @param getKey       A jose-compatible key resolver — pass
  *                     `scope.jwks.getKey` from a `ConsumerScope`
@@ -3236,6 +3372,16 @@ declare class JwtNotYetValidError extends JwtVerifyError {
         cause?: unknown;
     });
 }
+/**
+ * The token is a refresh token (`token_use: "refresh"` or
+ * `type: "refresh"`). Refresh tokens are only valid at the refresh
+ * endpoint and must never authenticate an API request.
+ */
+declare class JwtRefreshTokenError extends JwtVerifyError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
 /** `iss` claim doesn't match the expected issuer. */
 declare class JwtIssuerMismatchError extends JwtVerifyError {
     constructor(message: string, options?: {
@@ -3286,7 +3432,15 @@ interface AuthConfig extends PCClientConfig {
     jwksTtlMs?: number;
 }
 declare class Auth {
+    /** Admin client: explicit `auth`, else `PRODUCTCRAFT_API_KEY`. */
     private readonly client;
+    /**
+     * Consumer client: explicit `auth` only. Consumer routes act for an
+     * end user, so a workspace key from the environment must never leak
+     * onto them. Pass `auth` explicitly for PAK-only consumer routes
+     * (`signup_requires_pak`, tenants, code mint, factors).
+     */
+    private readonly consumerClient;
     private readonly baseUrl;
     private readonly fetch;
     private readonly jwtConfig;
@@ -3294,15 +3448,20 @@ declare class Auth {
     /**
      * Returns an `AppScope` bound to the given appId. All operations under
      * `/v1/apps/{appId}/...` are exposed as resource namespaces on the
-     * returned object.
+     * returned object. Uses the explicit `auth`, else
+     * `PRODUCTCRAFT_API_KEY` from the environment.
      */
     app(appId: string): AppScope;
     /**
      * Returns a `ConsumerScope` bound to the given appSlug. Exposes the
      * `/{appSlug}/v1/...` surface (sign-in, sign-up, me, verify, oauth)
      * and the JWT-verify helper for tokens issued by this app.
+     *
+     * `appSlug` defaults to `PRODUCTCRAFT_AUTH_APP` from the environment.
+     * No credential is ever read from the environment for consumer
+     * routes; only an explicit `auth` is sent.
      */
-    consumer(appSlug: string): ConsumerScope;
+    consumer(appSlug?: string): ConsumerScope;
     readonly apps: {
         /** List apps the caller's workspace can see. */
         list: (params?: Partial<AppControllerListMyAppsQueryParams>) => Promise<AppListResponseDto>;
@@ -3319,4 +3478,4 @@ declare class Auth {
     };
 }
 
-export { AUTH_LEGACY_ISSUER, AppScope, type AssignRoleDto, Auth, type AuthClaims, type AuthConfig, AuthHttpError, type AuthorizeBatchBody, type AuthorizeBody, type ClientCredentialsDto, type ConfirmEnrollmentResponseDto, type ConsumerAcceptInviteDto, type ConsumerLogoutDto, type ConsumerRefreshDto, type ConsumerRequestPasswordResetDto, type ConsumerResetPasswordDto, ConsumerScope, type ConsumerSigninDto, type ConsumerSignupDto, type ConsumerTokenResponseDto, type CreateApiKeyDto, type CreateAppDto, type CreateEndUserInviteDto, type CreateM2MClientDto, type CreatePermissionDto, type CreateRoleDto, type EncodedPasskeyCredential, type EndUserInviteResponseDto, type IdpNativeSigninDto, type IdpNativeUserHintDto, type IdpTokenResponseDto, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtVerifyError, type PasskeyBrowserOptions, type PasskeyCredentialLike, type PasskeyCredentialsContainer, type PasskeyDecodedOptions, PasskeyError, type PasskeyErrorCode, type PasskeyMediation, type PasskeyPublicKeyOptions, type PublicFactorDto, type SetPermissionsDto, type SetScopesDto, type StepUpResponseDto, type UpdateAppDto, type UpdateAppStatusDto, type UpdateAuthConfigDto, type UpdateEndUserDto, type UpdateEndUserRoleDto, type UpdateEndUserStatusDto, type UpdateM2MClientDto, type UpdateMeDto, type UpdateRoleDto, type VerifyBody, type VerifyOptions, type WebauthnCredentialDto, createPasskeyCredential, decodeOptions, encodeCredential, fromB64u, getPasskeyCredential, isPasskeySupported, toB64u, verifyAuthToken };
+export { AUTH_LEGACY_ISSUER, AppScope, type AssignRoleDto, Auth, type AuthClaims, type AuthConfig, AuthHttpError, type AuthorizeBatchBody, type AuthorizeBody, type ClientCredentialsDto, type ConfirmEnrollmentResponseDto, type ConsumerAcceptInviteDto, type ConsumerLogoutDto, type ConsumerRefreshDto, type ConsumerRequestPasswordResetDto, type ConsumerResetPasswordDto, ConsumerScope, type ConsumerSigninDto, type ConsumerSignupDto, type ConsumerTokenResponseDto, type CreateApiKeyDto, type CreateAppDto, type CreateEndUserInviteDto, type CreateM2MClientDto, type CreatePermissionDto, type CreateRoleDto, type EncodedPasskeyCredential, type EndUserInviteResponseDto, type IdpNativeSigninDto, type IdpNativeUserHintDto, type IdpTokenResponseDto, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtRefreshTokenError, JwtVerifyError, type PasskeyBrowserOptions, type PasskeyCredentialLike, type PasskeyCredentialsContainer, type PasskeyDecodedOptions, PasskeyError, type PasskeyErrorCode, type PasskeyMediation, type PasskeyPublicKeyOptions, type PublicFactorDto, type SetPermissionsDto, type SetScopesDto, type StepUpResponseDto, type UpdateAppDto, type UpdateAppStatusDto, type UpdateAuthConfigDto, type UpdateEndUserDto, type UpdateEndUserRoleDto, type UpdateEndUserStatusDto, type UpdateM2MClientDto, type UpdateMeDto, type UpdateRoleDto, type VerifyBody, type VerifyOptions, type WebauthnCredentialDto, createPasskeyCredential, decodeOptions, encodeCredential, fromB64u, getPasskeyCredential, isPasskeySupported, isRefreshToken, toB64u, verifyAuthToken };

package/dist/index.d.ts

@@ -156,7 +156,7 @@ declare class AuthHttpError<TData = unknown> extends Error {
  */
 type AuditLogEntryDto = {
     /**
-     * @description Canonical action string (e.g. `app.member.removed`, `role.created`).
+     * @description Canonical action string (e.g. `app.member.removed`, `role.created`). Account deletions: `auth.account.deleted` (one row per account, written in the deleting transaction; `resource` is `account`, `resource_id` the deleted account id, `metadata` `{ via, username, email_domain, created_at, verified }` where `via` is `platform`, `platform_bulk`, `consumer_admin` or `self`, plus `selection` (`{ mode, filter? }`) on bulk rows) and `auth.account.expired_unverified` (the unverified-account expiry job).
      * @type string
      */
     action: string;
@@ -981,6 +981,48 @@ type EndUserInviteListResponseDto = {
  * Generated by Kubb (https://kubb.dev/).
  * Do not edit manually.
  */
+declare const botProtectionResponseDtoProviderEnum: {
+    readonly turnstile: "turnstile";
+    readonly hcaptcha: "hcaptcha";
+};
+type BotProtectionResponseDtoProviderEnumKey = (typeof botProtectionResponseDtoProviderEnum)[keyof typeof botProtectionResponseDtoProviderEnum];
+type BotProtectionResponseDto = {
+    /**
+     * @description Whether sign-up requires a verified token.
+     * @type boolean
+     */
+    enabled: boolean;
+    /**
+     * @description Hostnames a solved challenge must come from. Empty = any.
+     * @type array
+     */
+    expected_hostnames: string[];
+    /**
+     * @type string
+     */
+    provider: BotProtectionResponseDtoProviderEnumKey;
+    /**
+     * @description Last four characters of the stored secret, so you can tell which one it is. null when none is stored.
+     * @type string
+     */
+    secret_last4: string | null;
+    /**
+     * @description Whether a provider secret is stored. The secret itself is never returned.
+     * @type boolean
+     */
+    secret_set: boolean;
+    /**
+     * @description Public widget site key.
+     * @type string
+     */
+    site_key: string;
+};
+
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+
 declare const authConfigResponseDtoMfaEnum: {
     readonly optional: "optional";
     readonly required: "required";
@@ -1007,6 +1049,10 @@ type AuthConfigResponseDto = {
      * @type array
      */
     allowed_redirect_origins: string[];
+    /**
+     * @description Sign-up bot protection; null when not configured.
+     */
+    bot_protection: BotProtectionResponseDto | null;
     /**
      * @type boolean
      */
@@ -1071,6 +1117,18 @@ type AuthConfigResponseDto = {
      * @type boolean
      */
     signup_enabled: boolean;
+    /**
+     * @description When true, sign-up requires a Platform API Key from this app\'s workspace (anonymous sign-ups get 401).
+     * @type boolean
+     */
+    signup_requires_pak: boolean;
+    /**
+     * @description Days an account may keep an unverified primary email before it is deleted. null = never.
+     * @minLength 1
+     * @maxLength 90
+     * @type number
+     */
+    unverified_account_ttl_days: number | null;
 };
 
 /**
@@ -1133,6 +1191,46 @@ type UpdateAppStatusDto = {
  * Generated by Kubb (https://kubb.dev/).
  * Do not edit manually.
  */
+declare const updateBotProtectionDtoProviderEnum: {
+    readonly turnstile: "turnstile";
+    readonly hcaptcha: "hcaptcha";
+};
+type UpdateBotProtectionDtoProviderEnumKey = (typeof updateBotProtectionDtoProviderEnum)[keyof typeof updateBotProtectionDtoProviderEnum];
+type UpdateBotProtectionDto = {
+    /**
+     * @description When true, every sign-up on this app must carry a `bot_protection_token` the provider accepts. Needs a stored secret. Takes effect within seconds.
+     * @type boolean | undefined
+     */
+    enabled?: boolean;
+    /**
+     * @description Hostnames the solved challenge must come from, as the provider reports them (exact match, no scheme, port or path). Empty (default) accepts any hostname the site key allows. Send null or [] to clear.
+     * @type array
+     */
+    expected_hostnames?: string[] | null;
+    /**
+     * @description Which CAPTCHA the app\'s sign-up form renders: Cloudflare Turnstile or hCaptcha. Required the first time the block is configured. Changing it without sending a new `secret` clears the stored secret, which belonged to the other provider.
+     * @type string | undefined
+     */
+    provider?: UpdateBotProtectionDtoProviderEnumKey;
+    /**
+     * @description The provider secret Auth verifies tokens with. WRITE-ONLY: no response ever returns it (GET shows `secret_set` and the last four characters). Send a string to store or replace it, null to clear it, or leave it out to keep the stored one. Stored encrypted.
+     * @maxLength 512
+     * @type string
+     */
+    secret?: string | null;
+    /**
+     * @description The public site key your sign-up page renders the widget with. Not a secret. Required the first time the block is configured.
+     * @maxLength 256
+     * @type string | undefined
+     */
+    site_key?: string;
+};
+
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+
 declare const updateAuthConfigDtoMfaEnum: {
     readonly optional: "optional";
     readonly required: "required";
@@ -1163,6 +1261,10 @@ type UpdateAuthConfigDto = {
      * @type array | undefined
      */
     allowed_redirect_origins?: string[];
+    /**
+     * @description Sign-up bot protection (Cloudflare Turnstile or hCaptcha). Fields you send are merged onto the stored block; send null to remove the block and its secret. While `enabled`, sign-up requires a `bot_protection_token` the provider accepts, checked before anything else, and fails closed (503) when the provider cannot be reached.
+     */
+    bot_protection?: UpdateBotProtectionDto | null;
     /**
      * @description When true, Consumer-API routes annotated with `@RequireAppPermission(perm)` enforce the requested perm against the EndUser\'s role-resolved permission set. When false (default), permission checks are bypassed — any valid token can call any annotated route. Flip on once you\'ve authored roles + permissions for this app and want them to actually mean something.
      * @type boolean | undefined
@@ -1253,6 +1355,18 @@ type UpdateAuthConfigDto = {
      * @type boolean | undefined
      */
     signup_enabled?: boolean;
+    /**
+     * @description When true, sign-up only works from your backend: every `POST /{app_slug}/v1/auth/signup` must carry a Platform API Key (`Authorization: Bearer pcft_live_…`) from this app\'s workspace whose policy allows `auth.signup.create` on this app. Anonymous sign-ups get 401. Use it when your own backend gates sign-ups (CAPTCHA, invite or payment checks). Independent of `bot_protection`; an app can use both. Turning it on for an app that has no workspace is refused with 409.
+     * @type boolean | undefined
+     */
+    signup_requires_pak?: boolean;
+    /**
+     * @description Delete accounts whose primary email is still unverified this many days after sign-up. Only self-sign-ups that never signed in after sign-up, hold no two-step factor, no verified contact and no social login qualify. Deletion is permanent, frees the email address and username, is audited as `auth.account.expired_unverified` and fires `user.deleted` with `reason: \"unverified_expired\"`. Send null to never delete. New apps start at 7; apps created before this setting existed start at null.
+     * @minLength 1
+     * @maxLength 90
+     * @type number
+     */
+    unverified_account_ttl_days?: number | null;
 };
 
 /**
@@ -1306,6 +1420,13 @@ type UpdateEndUserDto = {
      * @type string | undefined
      */
     email?: string;
+    /**
+     * @description Keys to merge into the end-user\'s metadata (shallow; a key set to null is removed; at most 8 KB stored). Set `app_active: true` to mark someone who uses your app: the unverified-account expiry never deletes an account carrying it.
+     * @type object | undefined
+     */
+    metadata?: {
+        [key: string]: any;
+    };
 };
 
 /**
@@ -2142,6 +2263,12 @@ type ConsumerAuthControllerSignin200 = ConsumerTokenResponseDto | ConsumerMfaCha
  * Do not edit manually.
  */
 type ConsumerSignupDto = {
+    /**
+     * @description The response token from the app\'s bot-protection widget (Cloudflare Turnstile or hCaptcha). Required when the app has bot protection switched on (`auth_config.bot_protection.enabled`); ignored otherwise. Auth verifies it with the provider before anything else about the sign-up is looked at. Tokens are single-use and expire after a few minutes, so render a fresh widget for every attempt. A backend that signs users up with a Platform API Key forwards the token its browser received.
+     * @maxLength 2048
+     * @type string | undefined
+     */
+    bot_protection_token?: string;
     /**
      * @description Optional display name shown back to the user.
      * @type string | undefined
@@ -2823,9 +2950,18 @@ interface VerifyOptions {
     /** Maximum token age — passed straight to jose. */
     maxTokenAge?: string | number;
 }
+/**
+ * True when the claims mark a refresh token: `token_use: "refresh"`
+ * (current shape) or `type: "refresh"` (older Auth tokens). Refresh
+ * tokens must never authenticate a request.
+ */
+declare function isRefreshToken(claims: Record<string, unknown> | null | undefined): boolean;
 /**
  * Verify an Auth-issued JWT against a JWKS resolver.
  *
+ * Refresh tokens are refused with `JwtRefreshTokenError` even when the
+ * signature, issuer and audience are valid.
+ *
  * @param token        The compact-form JWT (header.payload.signature)
  * @param getKey       A jose-compatible key resolver — pass
  *                     `scope.jwks.getKey` from a `ConsumerScope`
@@ -3236,6 +3372,16 @@ declare class JwtNotYetValidError extends JwtVerifyError {
         cause?: unknown;
     });
 }
+/**
+ * The token is a refresh token (`token_use: "refresh"` or
+ * `type: "refresh"`). Refresh tokens are only valid at the refresh
+ * endpoint and must never authenticate an API request.
+ */
+declare class JwtRefreshTokenError extends JwtVerifyError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
 /** `iss` claim doesn't match the expected issuer. */
 declare class JwtIssuerMismatchError extends JwtVerifyError {
     constructor(message: string, options?: {
@@ -3286,7 +3432,15 @@ interface AuthConfig extends PCClientConfig {
     jwksTtlMs?: number;
 }
 declare class Auth {
+    /** Admin client: explicit `auth`, else `PRODUCTCRAFT_API_KEY`. */
     private readonly client;
+    /**
+     * Consumer client: explicit `auth` only. Consumer routes act for an
+     * end user, so a workspace key from the environment must never leak
+     * onto them. Pass `auth` explicitly for PAK-only consumer routes
+     * (`signup_requires_pak`, tenants, code mint, factors).
+     */
+    private readonly consumerClient;
     private readonly baseUrl;
     private readonly fetch;
     private readonly jwtConfig;
@@ -3294,15 +3448,20 @@ declare class Auth {
     /**
      * Returns an `AppScope` bound to the given appId. All operations under
      * `/v1/apps/{appId}/...` are exposed as resource namespaces on the
-     * returned object.
+     * returned object. Uses the explicit `auth`, else
+     * `PRODUCTCRAFT_API_KEY` from the environment.
      */
     app(appId: string): AppScope;
     /**
      * Returns a `ConsumerScope` bound to the given appSlug. Exposes the
      * `/{appSlug}/v1/...` surface (sign-in, sign-up, me, verify, oauth)
      * and the JWT-verify helper for tokens issued by this app.
+     *
+     * `appSlug` defaults to `PRODUCTCRAFT_AUTH_APP` from the environment.
+     * No credential is ever read from the environment for consumer
+     * routes; only an explicit `auth` is sent.
      */
-    consumer(appSlug: string): ConsumerScope;
+    consumer(appSlug?: string): ConsumerScope;
     readonly apps: {
         /** List apps the caller's workspace can see. */
         list: (params?: Partial<AppControllerListMyAppsQueryParams>) => Promise<AppListResponseDto>;
@@ -3319,4 +3478,4 @@ declare class Auth {
     };
 }
 
-export { AUTH_LEGACY_ISSUER, AppScope, type AssignRoleDto, Auth, type AuthClaims, type AuthConfig, AuthHttpError, type AuthorizeBatchBody, type AuthorizeBody, type ClientCredentialsDto, type ConfirmEnrollmentResponseDto, type ConsumerAcceptInviteDto, type ConsumerLogoutDto, type ConsumerRefreshDto, type ConsumerRequestPasswordResetDto, type ConsumerResetPasswordDto, ConsumerScope, type ConsumerSigninDto, type ConsumerSignupDto, type ConsumerTokenResponseDto, type CreateApiKeyDto, type CreateAppDto, type CreateEndUserInviteDto, type CreateM2MClientDto, type CreatePermissionDto, type CreateRoleDto, type EncodedPasskeyCredential, type EndUserInviteResponseDto, type IdpNativeSigninDto, type IdpNativeUserHintDto, type IdpTokenResponseDto, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtVerifyError, type PasskeyBrowserOptions, type PasskeyCredentialLike, type PasskeyCredentialsContainer, type PasskeyDecodedOptions, PasskeyError, type PasskeyErrorCode, type PasskeyMediation, type PasskeyPublicKeyOptions, type PublicFactorDto, type SetPermissionsDto, type SetScopesDto, type StepUpResponseDto, type UpdateAppDto, type UpdateAppStatusDto, type UpdateAuthConfigDto, type UpdateEndUserDto, type UpdateEndUserRoleDto, type UpdateEndUserStatusDto, type UpdateM2MClientDto, type UpdateMeDto, type UpdateRoleDto, type VerifyBody, type VerifyOptions, type WebauthnCredentialDto, createPasskeyCredential, decodeOptions, encodeCredential, fromB64u, getPasskeyCredential, isPasskeySupported, toB64u, verifyAuthToken };
+export { AUTH_LEGACY_ISSUER, AppScope, type AssignRoleDto, Auth, type AuthClaims, type AuthConfig, AuthHttpError, type AuthorizeBatchBody, type AuthorizeBody, type ClientCredentialsDto, type ConfirmEnrollmentResponseDto, type ConsumerAcceptInviteDto, type ConsumerLogoutDto, type ConsumerRefreshDto, type ConsumerRequestPasswordResetDto, type ConsumerResetPasswordDto, ConsumerScope, type ConsumerSigninDto, type ConsumerSignupDto, type ConsumerTokenResponseDto, type CreateApiKeyDto, type CreateAppDto, type CreateEndUserInviteDto, type CreateM2MClientDto, type CreatePermissionDto, type CreateRoleDto, type EncodedPasskeyCredential, type EndUserInviteResponseDto, type IdpNativeSigninDto, type IdpNativeUserHintDto, type IdpTokenResponseDto, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtRefreshTokenError, JwtVerifyError, type PasskeyBrowserOptions, type PasskeyCredentialLike, type PasskeyCredentialsContainer, type PasskeyDecodedOptions, PasskeyError, type PasskeyErrorCode, type PasskeyMediation, type PasskeyPublicKeyOptions, type PublicFactorDto, type SetPermissionsDto, type SetScopesDto, type StepUpResponseDto, type UpdateAppDto, type UpdateAppStatusDto, type UpdateAuthConfigDto, type UpdateEndUserDto, type UpdateEndUserRoleDto, type UpdateEndUserStatusDto, type UpdateM2MClientDto, type UpdateMeDto, type UpdateRoleDto, type VerifyBody, type VerifyOptions, type WebauthnCredentialDto, createPasskeyCredential, decodeOptions, encodeCredential, fromB64u, getPasskeyCredential, isPasskeySupported, isRefreshToken, toB64u, verifyAuthToken };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { PC_BASE_URL } from '@productcraft/core';
+import { PC_BASE_URL, resolveAuth, readEnv, PC_AUTH_APP_ENV } from '@productcraft/core';
 import { createRemoteJWKSet, errors, jwtVerify, customFetch } from 'jose';
 
 // src/index.ts
@@ -2068,6 +2068,12 @@ var JwtNotYetValidError = class extends JwtVerifyError {
     this.name = "JwtNotYetValidError";
   }
 };
+var JwtRefreshTokenError = class extends JwtVerifyError {
+  constructor(message = "Refresh tokens cannot be used as access tokens", options) {
+    super("ERR_JWT_REFRESH_TOKEN", message, options);
+    this.name = "JwtRefreshTokenError";
+  }
+};
 var JwtIssuerMismatchError = class extends JwtVerifyError {
   constructor(message, options) {
     super("ERR_JWT_ISS_MISMATCH", message, options);
@@ -2148,6 +2154,10 @@ var JwksCache = class {
   refresh() {
   }
 };
+function isRefreshToken(claims) {
+  if (!claims) return false;
+  return claims.token_use === "refresh" || claims.type === "refresh";
+}
 async function verifyAuthToken(token, getKey, opts = {}) {
   try {
     const { payload } = await jwtVerify(token, getKey, {
@@ -2159,6 +2169,7 @@ async function verifyAuthToken(token, getKey, opts = {}) {
       currentDate: opts.currentDate,
       maxTokenAge: opts.maxTokenAge
     });
+    if (isRefreshToken(payload)) throw new JwtRefreshTokenError();
     return payload;
   } catch (err) {
     throw translateJoseError(err);
@@ -2700,7 +2711,15 @@ async function statsControllerGetMyStats({ params } = {}, config = {}) {
 
 // src/index.ts
 var Auth = class {
+  /** Admin client: explicit `auth`, else `PRODUCTCRAFT_API_KEY`. */
   client;
+  /**
+   * Consumer client: explicit `auth` only. Consumer routes act for an
+   * end user, so a workspace key from the environment must never leak
+   * onto them. Pass `auth` explicitly for PAK-only consumer routes
+   * (`signup_requires_pak`, tenants, code mint, factors).
+   */
+  consumerClient;
   baseUrl;
   fetch;
   jwtConfig;
@@ -2708,6 +2727,11 @@ var Auth = class {
     this.baseUrl = config.baseUrl ?? PC_BASE_URL.auth;
     this.fetch = config.fetch;
     this.client = makeAuthHttpClient({
+      baseUrl: this.baseUrl,
+      auth: resolveAuth(config.auth),
+      fetch: this.fetch
+    });
+    this.consumerClient = makeAuthHttpClient({
       baseUrl: this.baseUrl,
       auth: config.auth,
       fetch: this.fetch
@@ -2719,7 +2743,8 @@ var Auth = class {
   /**
    * Returns an `AppScope` bound to the given appId. All operations under
    * `/v1/apps/{appId}/...` are exposed as resource namespaces on the
-   * returned object.
+   * returned object. Uses the explicit `auth`, else
+   * `PRODUCTCRAFT_API_KEY` from the environment.
    */
   app(appId) {
     return new AppScope(appId, this.client);
@@ -2728,11 +2753,21 @@ var Auth = class {
    * Returns a `ConsumerScope` bound to the given appSlug. Exposes the
    * `/{appSlug}/v1/...` surface (sign-in, sign-up, me, verify, oauth)
    * and the JWT-verify helper for tokens issued by this app.
+   *
+   * `appSlug` defaults to `PRODUCTCRAFT_AUTH_APP` from the environment.
+   * No credential is ever read from the environment for consumer
+   * routes; only an explicit `auth` is sent.
    */
   consumer(appSlug) {
+    const slug = appSlug ?? readEnv(PC_AUTH_APP_ENV);
+    if (!slug) {
+      throw new Error(
+        `@productcraft/auth: consumer() needs an app slug. Pass one, or set ${PC_AUTH_APP_ENV}.`
+      );
+    }
     return new ConsumerScope(
-      appSlug,
-      { client: this.client, baseUrl: this.baseUrl, fetch: this.fetch },
+      slug,
+      { client: this.consumerClient, baseUrl: this.baseUrl, fetch: this.fetch },
       this.jwtConfig
     );
   }
@@ -2771,6 +2806,6 @@ var Auth = class {
   };
 };
 
-export { AUTH_LEGACY_ISSUER, AppScope, Auth, AuthHttpError, ConsumerScope, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtVerifyError, PasskeyError, createPasskeyCredential, decodeOptions, encodeCredential, fromB64u, getPasskeyCredential, isPasskeySupported, toB64u, verifyAuthToken };
+export { AUTH_LEGACY_ISSUER, AppScope, Auth, AuthHttpError, ConsumerScope, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtRefreshTokenError, JwtVerifyError, PasskeyError, createPasskeyCredential, decodeOptions, encodeCredential, fromB64u, getPasskeyCredential, isPasskeySupported, isRefreshToken, toB64u, verifyAuthToken };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map