@spfn/auth 0.3.0-beta.6 → 0.3.0-beta.7

package/README.md

@@ -1178,6 +1178,70 @@ app.post('/v1/echo', createClientProofGuard(state), (c) => { /* handler */ });
 Responses and errors MUST be canonical bytes with the contract envelope — build them with
 `encodeCanonicalJson`/`ClientProofRefusal`, never `c.json()` (key order and int64 differ).
 
+## Custom auth profiles (`registerAuthProfile`)
+
+`clientProofV1` is not a special case in the middleware — it is one entry in a registry
+`authenticate` and `optionalAuth` dispatch on. An app registers its own scheme the same way,
+without forking the middleware or wrapping it:
+
+```typescript
+import { registerAuthProfile, type AuthContext } from '@spfn/auth/server';
+import { UnauthorizedError } from '@spfn/core/errors';
+
+// At boot — server.config.ts, before the server starts taking requests.
+registerAuthProfile('serviceTokenV1', {
+    verify: async (c): Promise<AuthContext> =>
+    {
+        const user = await findServiceAccount(c.req.header('x-acme-service-token'));
+        if (user === null)
+        {
+            // A refusal leaves the verifier as a throw. It reaches the app's
+            // error handler exactly as the Bearer path's does.
+            throw new UnauthorizedError({ message: 'Invalid service token' });
+        }
+
+        return {
+            user,
+            userId: String(user.id),
+            keyId: 'service-token',
+            role: null,
+            locale: 'en',
+            scheme: 'serviceTokenV1',
+        };
+    },
+});
+```
+
+A request naming the profile is then answered by that verifier:
+
+```http
+POST /v1/reports
+x-spfn-auth-profile: serviceTokenV1
+x-acme-service-token: <the app's own credential>
+```
+
+- **Register at boot, before the first request.** The registry is read on every dispatch, so a
+  profile registered later is simply a profile the requests before it did not have. Registration
+  is not frozen after startup — it is a contract, not a runtime check.
+- **A duplicate name throws**, `clientProofV1` included. Replacing a registered verifier silently
+  is how an import order or a copied profile name swaps the code that decides who is admitted, so
+  there is no override — and no unregistration API for the same reason.
+- **The verifier must expose a callable `verify`**, and what it resolves must carry a `userId` — a
+  verifier that cannot admit anyone is refused at boot, and a resolve without a principal (`null`,
+  the JS idiom for "no user") is refused as a throw rather than routed as authenticated.
+- **An unknown profile is still refused** (`PROFILE_REJECTED`, 400): registering one name does not
+  open the header to others.
+- **Mixing is still refused.** A request carrying both `x-spfn-auth-profile` and `Authorization` is
+  rejected before either path runs; a custom verifier never sees it.
+- **A verifier's throw propagates**, and only the internal clientProofV1 contract refusal is
+  answered with the canonical envelope. Under `optionalAuth` too: credentials that were presented
+  and refused are never downgraded to anonymous passage — only "presented nothing" continues
+  without an auth context.
+- **`AuthContext.scheme` is an open union** — `'bearer' | 'clientProofV1' | 'oneTimeToken' | (string
+  & {})`. The built-in names keep their autocomplete and a registered profile names its own scheme.
+  The field stays informational: downstream permission and tenant code takes one principal shape and
+  never branches on how it was produced.
+
 ## Account Deletion & Recovery
 
 Grace-period deletion with in-window recovery, an admin/GDPR-response entry point for immediate

package/dist/{authenticate-98lBIMxP.d.ts → authenticate-Mg9D7Nys.d.ts}

@@ -993,7 +993,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
             id: number;
             name: string;
             displayName: string;
-            category: "auth" | "custom" | "user" | "rbac" | "system" | undefined;
+            category: "custom" | "user" | "auth" | "rbac" | "system" | undefined;
         }[];
         userId: number;
         publicId: string;
@@ -1293,8 +1293,8 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     }, {}, {
         roles: {
             description: string | null;
-            name: string;
             id: number;
+            name: string;
             displayName: string;
             isBuiltin: boolean;
             isSystem: boolean;
@@ -1315,8 +1315,8 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     }, {}, {
         role: {
             description: string | null;
-            name: string;
             id: number;
+            name: string;
             displayName: string;
             isBuiltin: boolean;
             isSystem: boolean;
@@ -1339,8 +1339,8 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     }, {}, {
         role: {
             description: string | null;
-            name: string;
             id: number;
+            name: string;
             displayName: string;
             isBuiltin: boolean;
             isSystem: boolean;
@@ -1424,6 +1424,11 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
  * downstream permission/tenant code consumes one principal shape and never
  * branches on how it was authenticated.
  *
+ * An app adds its own scheme with `registerAuthProfile` at boot. The dispatch
+ * it joins is the one below, unchanged: a name nobody registered is still
+ * refused, and profile credentials mixed with an Authorization header are
+ * still refused before either path runs.
+ *
  * The clientProofV1 verifier reuses the phase-1 admission pieces (header
  * shape, canonical body, proof-input assembly, ECDSA verification) with two
  * production substitutions: the key directory is `user_public_keys` via
@@ -1444,8 +1449,13 @@ interface AuthContext {
     keyId: string;
     role: string | null;
     locale: string;
-    /** How the principal was authenticated. Informational — downstream code never branches on it. */
-    scheme: 'bearer' | 'clientProofV1' | 'oneTimeToken';
+    /**
+     * How the principal was authenticated. Informational — downstream code
+     * never branches on it. The union stays open for the profiles an app
+     * registers itself: the built-in names keep their autocomplete, and a
+     * registered profile names its own scheme without editing this file.
+     */
+    scheme: 'bearer' | 'clientProofV1' | 'oneTimeToken' | (string & {});
 }
 /** A profile's verifier: admits the request and returns the principal, or throws. */
 interface AuthProfileVerifier {
@@ -1492,6 +1502,49 @@ type AuthProfileOutcome = {
  * handed to the generic error handler is classified by its class name instead.
  */
 declare function runAuthProfile(c: Context): Promise<AuthProfileOutcome>;
+/**
+ * Registers an app's own verifier under a profile name.
+ *
+ * Call it at boot, before the first request: the registry is a module-global
+ * read on every dispatch, so a profile registered later is simply a profile
+ * the requests before it did not have. There is no freeze and no
+ * unregistration — an auth surface that can be rearranged at runtime is a
+ * surface an app bug can rearrange.
+ *
+ * A duplicate name throws rather than replacing the verifier that holds it,
+ * `clientProofV1` included. A silent override is how a second import order, or
+ * a copied profile name, quietly swaps the code that decides who is admitted.
+ *
+ * The verifier must expose a callable `verify` — a value that cannot admit
+ * anyone is refused at boot rather than becoming a registry entry the dispatch
+ * reads as "no profile header", which is anonymous passage under
+ * `optionalAuth` for a request that presented profile credentials.
+ *
+ * The verifier returns the same `AuthContext` the Bearer path sets and refuses
+ * by throwing. A resolve that carries no `userId` is refused as a throw too —
+ * "no user" is a refusal, never a principal. A throw is not caught here:
+ * `runAuthProfile` answers the internal clientProofV1 contract refusal and
+ * nothing else, so a verifier's own error reaches the app's generic error
+ * handler exactly as the Bearer path's `UnauthorizedError` does — and never
+ * becomes anonymous passage, not even under `optionalAuth`.
+ *
+ * @example
+ * ```typescript
+ * registerAuthProfile('serviceTokenV1', {
+ *     verify: async (c) =>
+ *     {
+ *         const user = await authenticateServiceToken(c.req.header('x-acme-service-token'));
+ *         if (user === null)
+ *         {
+ *             throw new UnauthorizedError({ message: 'Invalid service token' });
+ *         }
+ *
+ *         return { user, userId: String(user.id), keyId: 'service', role: null, locale: 'en', scheme: 'serviceTokenV1' };
+ *     },
+ * });
+ * ```
+ */
+declare function registerAuthProfile(profileId: string, verifier: AuthProfileVerifier): void;
 
 declare module 'hono' {
     interface ContextVariableMap {
@@ -1558,4 +1611,4 @@ declare const authenticate: _spfn_core_route.NamedMiddleware<"auth">;
  */
 declare const optionalAuth: _spfn_core_route.NamedMiddleware<"optionalAuth">;
 
-export { type SendVerificationCodeParams as $, type AuthInitOptions as A, type OAuthCodeExchangeOptions as B, type ConfirmSignupLinkResult as C, DeviceNameSchema as D, EmailSchema as E, type OAuthNativeParams as F, type OAuthStartParams as G, type OAuthTokens as H, type IssueOneTimeTokenResult as I, PasswordSchema as J, type KeySummary as K, type LoginResult as L, PhoneSchema as M, type NativeVerifyOptions as N, type OAuthStartResult as O, type PermissionConfig as P, PlatformSchema as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type RegisterParams as T, type UserProfile as U, VERIFICATION_PURPOSES as V, type RegisterPublicKeyParams as W, type RequestSignupLinkParams as X, type RevokeAllKeysParams as Y, type RevokeKeyParams as Z, type RotateKeyParams as _, type RegisterResult as a, TargetTypeSchema as a0, type UnlinkNotification as a1, UnlinkNotifyRejection as a2, type UnlinkNotifyRequest as a3, type UnlinkNotifyResult as a4, VerificationPurposeSchema as a5, type VerifyCodeParams as a6, type VerifyCodeResult as a7, authenticate as a8, buildOAuthErrorUrl as a9, rotateKeyService as aA, runAuthProfile as aB, selectAuthProfile as aC, sendVerificationCodeService as aD, verifyCodeService as aE, verifyOneTimeTokenService as aF, changePasswordService as aa, completeSignupService as ab, confirmSignupLinkService as ac, getEnabledOAuthProviders as ad, getGoogleAccessToken as ae, getOAuthProvider as af, getRegisteredProviders as ag, isOAuthProviderEnabled as ah, isSafeReturnPath as ai, issueOneTimeTokenService as aj, listKeysService as ak, loginService as al, logoutService as am, oauthCallbackService as an, oauthNativeService as ao, oauthStartService as ap, oauthUnlinkNotifyService as aq, optionalAuth as ar, registerOAuthProvider as as, registerPublicKeyService as at, registerService as au, requestSignupLinkService as av, requireEnabledProvider as aw, resolveAuthenticatedUser as ax, revokeAllKeysService as ay, revokeKeyService as az, type RequestSignupLinkResult as b, type RotateKeyResult as c, type RevokeAllKeysResult as d, type OAuthNativeResult as e, type ProfileInfo as f, type AuthSession as g, PERMISSION_CATEGORIES as h, type PermissionCategory as i, VERIFICATION_TARGET_TYPES as j, type VerificationPurpose as k, type VerificationTargetType as l, mainAuthRouter as m, type OAuthProvider as n, type AuthContext as o, type AuthProfileOutcome as p, type AuthProfileVerifier as q, type ChangePasswordParams as r, type CompleteSignupParams as s, type ConfirmSignupLinkParams as t, KEY_FINGERPRINT_PREFIX_LENGTH as u, type LoginParams as v, type LogoutParams as w, type NormalizedIdentity as x, type OAuthCallbackParams as y, type OAuthCallbackResult as z };
+export { type SendVerificationCodeParams as $, type AuthInitOptions as A, type OAuthCodeExchangeOptions as B, type ConfirmSignupLinkResult as C, DeviceNameSchema as D, EmailSchema as E, type OAuthNativeParams as F, type OAuthStartParams as G, type OAuthTokens as H, type IssueOneTimeTokenResult as I, PasswordSchema as J, type KeySummary as K, type LoginResult as L, PhoneSchema as M, type NativeVerifyOptions as N, type OAuthStartResult as O, type PermissionConfig as P, PlatformSchema as Q, type RoleConfig as R, type SendVerificationCodeResult as S, type RegisterParams as T, type UserProfile as U, VERIFICATION_PURPOSES as V, type RegisterPublicKeyParams as W, type RequestSignupLinkParams as X, type RevokeAllKeysParams as Y, type RevokeKeyParams as Z, type RotateKeyParams as _, type RegisterResult as a, TargetTypeSchema as a0, type UnlinkNotification as a1, UnlinkNotifyRejection as a2, type UnlinkNotifyRequest as a3, type UnlinkNotifyResult as a4, VerificationPurposeSchema as a5, type VerifyCodeParams as a6, type VerifyCodeResult as a7, authenticate as a8, buildOAuthErrorUrl as a9, revokeKeyService as aA, rotateKeyService as aB, runAuthProfile as aC, selectAuthProfile as aD, sendVerificationCodeService as aE, verifyCodeService as aF, verifyOneTimeTokenService as aG, changePasswordService as aa, completeSignupService as ab, confirmSignupLinkService as ac, getEnabledOAuthProviders as ad, getGoogleAccessToken as ae, getOAuthProvider as af, getRegisteredProviders as ag, isOAuthProviderEnabled as ah, isSafeReturnPath as ai, issueOneTimeTokenService as aj, listKeysService as ak, loginService as al, logoutService as am, oauthCallbackService as an, oauthNativeService as ao, oauthStartService as ap, oauthUnlinkNotifyService as aq, optionalAuth as ar, registerAuthProfile as as, registerOAuthProvider as at, registerPublicKeyService as au, registerService as av, requestSignupLinkService as aw, requireEnabledProvider as ax, resolveAuthenticatedUser as ay, revokeAllKeysService as az, type RequestSignupLinkResult as b, type RotateKeyResult as c, type RevokeAllKeysResult as d, type OAuthNativeResult as e, type ProfileInfo as f, type AuthSession as g, PERMISSION_CATEGORIES as h, type PermissionCategory as i, VERIFICATION_TARGET_TYPES as j, type VerificationPurpose as k, type VerificationTargetType as l, mainAuthRouter as m, type OAuthProvider as n, type AuthContext as o, type AuthProfileOutcome as p, type AuthProfileVerifier as q, type ChangePasswordParams as r, type CompleteSignupParams as s, type ConfirmSignupLinkParams as t, KEY_FINGERPRINT_PREFIX_LENGTH as u, type LoginParams as v, type LogoutParams as w, type NormalizedIdentity as x, type OAuthCallbackParams as y, type OAuthCallbackResult as z };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _spfn_core_nextjs from '@spfn/core/nextjs';
-import { P as PermissionConfig, R as RoleConfig, m as mainAuthRouter, S as SendVerificationCodeResult, a as RegisterResult, b as RequestSignupLinkResult, C as ConfirmSignupLinkResult, L as LoginResult, c as RotateKeyResult, K as KeySummary, d as RevokeAllKeysResult, I as IssueOneTimeTokenResult, O as OAuthStartResult, e as OAuthNativeResult, U as UserProfile, f as ProfileInfo } from './authenticate-98lBIMxP.js';
-export { A as AuthInitOptions, g as AuthSession, h as PERMISSION_CATEGORIES, i as PermissionCategory, V as VERIFICATION_PURPOSES, j as VERIFICATION_TARGET_TYPES, k as VerificationPurpose, l as VerificationTargetType } from './authenticate-98lBIMxP.js';
+import { P as PermissionConfig, R as RoleConfig, m as mainAuthRouter, S as SendVerificationCodeResult, a as RegisterResult, b as RequestSignupLinkResult, C as ConfirmSignupLinkResult, L as LoginResult, c as RotateKeyResult, K as KeySummary, d as RevokeAllKeysResult, I as IssueOneTimeTokenResult, O as OAuthStartResult, e as OAuthNativeResult, U as UserProfile, f as ProfileInfo } from './authenticate-Mg9D7Nys.js';
+export { A as AuthInitOptions, g as AuthSession, h as PERMISSION_CATEGORIES, i as PermissionCategory, V as VERIFICATION_PURPOSES, j as VERIFICATION_TARGET_TYPES, k as VerificationPurpose, l as VerificationTargetType } from './authenticate-Mg9D7Nys.js';
 import * as _spfn_core_route from '@spfn/core/route';
 import { HttpMethod } from '@spfn/core/route';
 export { A as ACCOUNT_DELETION_REQUESTED_BY, a as ACCOUNT_DELETION_REQUEST_STATUSES, b as AccountDeletionRequestStatus, c as AccountDeletionRequestedBy, I as INVITATION_STATUSES, d as InvitationStatus, e as KEY_ALGORITHM, f as KEY_DEVICE_NAME_MAX_LENGTH, g as KEY_PLATFORM, K as KeyAlgorithmType, h as KeyPlatformType, P as PURGE_STRATEGIES, i as PurgeStrategy, S as SOCIAL_PROVIDERS, j as SocialProvider, U as USER_STATUSES, k as UserStatus } from './types-DYyhze28.js';
@@ -217,7 +217,7 @@ declare const authApi: _spfn_core_nextjs.Client<_spfn_core_route.Router<{
             id: number;
             name: string;
             displayName: string;
-            category: "auth" | "custom" | "user" | "rbac" | "system" | undefined;
+            category: "custom" | "user" | "auth" | "rbac" | "system" | undefined;
         }[];
         userId: number;
         publicId: string;
@@ -517,8 +517,8 @@ declare const authApi: _spfn_core_nextjs.Client<_spfn_core_route.Router<{
     }, {}, {
         roles: {
             description: string | null;
-            name: string;
             id: number;
+            name: string;
             displayName: string;
             isBuiltin: boolean;
             isSystem: boolean;
@@ -539,8 +539,8 @@ declare const authApi: _spfn_core_nextjs.Client<_spfn_core_route.Router<{
     }, {}, {
         role: {
             description: string | null;
-            name: string;
             id: number;
+            name: string;
             displayName: string;
             isBuiltin: boolean;
             isSystem: boolean;
@@ -563,8 +563,8 @@ declare const authApi: _spfn_core_nextjs.Client<_spfn_core_route.Router<{
     }, {}, {
         role: {
             description: string | null;
-            name: string;
             id: number;
+            name: string;
             displayName: string;
             isBuiltin: boolean;
             isSystem: boolean;