@stacksjs/auth 0.75.15 → 0.75.17

package/README.md

@@ -28,6 +28,26 @@ import auth from '@stacksjs/auth'
 
 Learn more in the docs.
 
+## OAuth authorization provider
+
+The authorization provider is opt-in through `config/auth.ts`. Enabling it
+requires an explicit issuer, registered scopes and resources, and a reviewed
+client policy. Provider routes remain unavailable until the complete consent
+and token-exchange flow is registered.
+
+The framework currently exports protocol primitives for incremental provider
+integration:
+
+- `resolveOAuthProviderConfig()` validates and snapshots provider policy.
+- `validateOAuthClientRegistration()` validates client-controlled metadata.
+- `validateOAuthAuthorizationRequest()` validates exact redirects, scopes,
+  resources, and S256 PKCE before login or consent.
+- `issueAuthorizationCode()` and `withAuthorizationCode()` provide hash-only,
+  short-lived, atomic, single-use authorization codes.
+
+These primitives do not turn personal access tokens into delegated OAuth
+tokens, and they do not register public endpoints by themselves.
+
 ## 🧪 Testing
 
 ```bash

package/dist/authentication.d.ts

@@ -20,6 +20,7 @@ export declare class Auth {
   static setUser(user: UserModel | undefined): void;
   static createTokenForUser(user: UserModel, options?: TokenCreateOptions): Promise<NewAccessToken>;
   static createToken(user: UserModel, name?: string, abilities?: string[]): Promise<AuthToken>;
+  static requestUserTokenWithClient(credentials: AuthCredentials, clientId: number, clientSecret: string): Promise<{ token: AuthToken } | null>;
   static requestToken(credentials: AuthCredentials, clientId: number, clientSecret: string): Promise<{ token: AuthToken } | null>;
   static validateToken(token: string): Promise<boolean>;
   static getUserFromToken(token: string): Promise<UserModel | undefined>;

package/dist/authentication.js

@@ -1 +1 @@
-import{config}from"@stacksjs/config";import{db,getDatabaseDialect,isInTransaction,parseSqlDateTime}from"@stacksjs/database/runtime";import{HttpError}from"@stacksjs/error-handling";import{formatDate,User}from"@stacksjs/orm";import{getCurrentRequest,request}from"@stacksjs/router";import{requestToken}from"./request-token";import{sessionLogout,sessionUser}from"./session-auth";import{revokeTokenPair,revokeTokenPairs}from"./token-revocation";import{Buffer}from"node:buffer";import{createHash,timingSafeEqual}from"node:crypto";import{decrypt,encrypt,verifyHash}from"@stacksjs/security";import{log}from"@stacksjs/logging";import{DUMMY_BCRYPT_HASH}from"./internal-constants";import{RateLimiter}from"./rate-limiter";import{withVerifiedPassword}from"./credential-version";import{tokenDate,tokenTimestamps}from"./token-dates";const REQUEST_AUTH_STATE_KEY=Symbol.for("stacks.requestAuthState");function authStateOrNull(){const req=getCurrentRequest();if(!req)return null;let state=req[REQUEST_AUTH_STATE_KEY];if(!state){state={};req[REQUEST_AUTH_STATE_KEY]=state}return state}function hashToken(token){return createHash("sha256").update(token).digest("hex")}import{createToken as createRawToken,DEFAULT_TOKENABLE_TYPE,deleteExpiredTokens,getPasswordChangedAt,isIssuedBeforePasswordChange,parseScopes}from"./tokens";export class Auth{static getBearerToken(){return requestToken(request)}static parseToken(token){const firstColonIndex=token.indexOf(":");if(firstColonIndex===-1)return null;const plainToken=token.substring(0,firstColonIndex),encryptedId=token.substring(firstColonIndex+1);if(!plainToken||!encryptedId)return null;return{plainToken,encryptedId}}static async getClientSecret(){const state=authStateOrNull();if(state?.clientSecret)return state.clientSecret;const client=await this.getPersonalAccessClient();if(state)state.clientSecret=client.secret;return client.secret}static async encryptTokenId(id){return await encrypt(String(id))}static async decryptTokenId(encryptedId){try{return await decrypt(encryptedId)}catch{try{const clientSecret=await this.getClientSecret();return await decrypt(encryptedId,clientSecret)}catch{return null}}}static async getPersonalAccessClient(){try{const client=await db.primary.selectFrom("oauth_clients").where("personal_access_client","=",!0).where("revoked","=",!1).selectAll().executeTakeFirst();if(!client)throw new HttpError(500,"No personal access client found. Please run `./buddy auth:setup` first.");return client}catch(error){if(error instanceof Error&&error.message.includes("does not exist"))throw new HttpError(500,"OAuth tables not found. Please run `./buddy auth:setup` first.");throw error}}static async verifiedClient(clientId,clientSecret){const client=await db.primary.selectFrom("oauth_clients").where("id","=",clientId).where("revoked","=",!1).selectAll().executeTakeFirst(),provided=Buffer.from(clientSecret);if(!client?.secret){const dummy=Buffer.alloc(Math.max(provided.length,1)),padded=provided.length>0?provided:Buffer.alloc(1);timingSafeEqual(dummy,padded);return null}const stored=String(client.secret);if(stored.startsWith("$2"))return await verifyHash(clientSecret,stored)?client:null;const storedBuf=Buffer.from(stored);if(storedBuf.length!==provided.length){timingSafeEqual(storedBuf,storedBuf);return null}return timingSafeEqual(storedBuf,provided)?client:null}static async getTokenFromId(tokenId){const result=await db.primary.selectFrom("oauth_access_tokens").where("id","=",tokenId).selectAll().executeTakeFirst();if(!result)return null;return this.tokenFromRow(result)}static tokenFromRow(token){return{id:token.id,userId:token.user_id,clientId:token.oauth_client_id,name:token.name||"auth-token",scopes:parseScopes(token.scopes),abilities:parseScopes(token.scopes),expiresAt:token.expires_at==null?null:tokenDate(token.expires_at),...tokenTimestamps(token),revoked:!!token.revoked}}static async attempt(credentials){const user=await this.verifyCredentials(credentials);if(!user)return!1;const state=authStateOrNull();if(state)state.authUser=user;return!0}static async verifyCredentials(credentials){const username=config.auth.username||"email",password=config.auth.password||"password",email=credentials[username];if(!email)return null;const isRateLimited=await RateLimiter.isRateLimited(email),user=await User.where("email","=",email).first(),authPass=credentials[password]||"",hashToVerify=user?.password||DUMMY_BCRYPT_HASH,hashCheck=await verifyHash(authPass,hashToVerify);if(isRateLimited)return null;if(hashCheck&&user){await RateLimiter.resetAttempts(email);return user}await RateLimiter.recordFailedAttempt(email);return null}static async validate(credentials){const username=config.auth.username||"email",password=config.auth.password||"password",email=credentials[username];if(!email)return!1;const user=await User.where("email","=",email).first(),authPass=credentials[password]||"",hashToVerify=user?.password||DUMMY_BCRYPT_HASH;return await verifyHash(authPass,hashToVerify)&&!!user}static async withVerifiedCredentials(credentials,issue){const user=await this.verifyCredentials(credentials);if(!user)return null;return withVerifiedPassword(user.id,user.password,()=>issue(user))}static async login(credentials,options){const result=await this.withVerifiedCredentials(credentials,async(user)=>{const{plainTextToken,refreshToken,expiresIn}=await this.createTokenForUser(user,options);return{user,token:plainTextToken,refreshToken,expiresIn}});if(!result)return null;const state=authStateOrNull();if(state)state.authUser=result.user;return result}static async loginUsingId(userId,options){let user;if(isInTransaction()){const definition=User.getDefinition();let query=db.primary.selectFrom(definition.table||"users").where(definition.primaryKey||"id","=",userId).selectAll();if(definition.traits?.useSoftDeletes)query=query.whereNull("deleted_at");const row=await query.executeTakeFirst();user=row?await User.make(row):null}else user=await User.find(userId);if(!user)return null;const state=authStateOrNull(),{plainTextToken,refreshToken,expiresIn}=await this.createTokenForUser(user,options);if(state)state.authUser=user;return{user,token:plainTextToken,refreshToken,expiresIn}}static async logout(){const bearerToken=this.getBearerToken();if(bearerToken)await this.revokeToken(bearerToken);else{const sessionId=getCurrentRequest()?.cookie?.("session_id");if(sessionId)await sessionLogout(sessionId)}const state=authStateOrNull();if(state){state.authUser=void 0;state.currentToken=void 0}const currentRequest=getCurrentRequest();if(currentRequest){currentRequest._authenticatedUser=void 0;currentRequest._currentAccessToken=void 0}}static async user(){const state=authStateOrNull();if(state?.authUser)return state.authUser;const bearerToken=this.getBearerToken(),sessionId=!bearerToken?getCurrentRequest()?.cookie?.("session_id"):void 0,user=bearerToken?await this.getUserFromToken(bearerToken):sessionId?await sessionUser(sessionId):void 0;if(user&&state)state.authUser=user;return user}static async check(){return await this.user()!==void 0}static async guest(){return!await this.check()}static async id(){return(await this.user())?.id}static setUser(user){const state=authStateOrNull();if(state)state.authUser=user}static async createTokenForUser(user,options){const name=options?.name??config.auth.defaultTokenName??"auth-token",abilities=options?.abilities??options?.scopes??config.auth.defaultAbilities??["*"],accessTtlMs=options?.expiresInMinutes!==void 0?options.expiresInMinutes*60*1000:config.auth.tokenExpiry??3600000,expiresAt=new Date(options?.expiresAt?.getTime()??Date.now()+accessTtlMs),refreshExpiresInDays=options?.refreshExpiresInDays??Math.max(1,Math.round((config.auth.refreshTokenExpiry??2592000000)/86400000));log.debug(`[auth] Creating token for user#${user.id}: ${name}`);const result=await createRawToken(user.id,name,abilities,{expiresAt,clientId:options?.clientId,withRefreshToken:options?.withRefreshToken!==!1,refreshExpiresInDays,userAgent:options?.userAgent??null,ipAddress:options?.ipAddress??null}),plainTextToken=result.plainTextToken;return{accessToken:{id:result.accessToken.id,userId:result.accessToken.userId,clientId:result.accessToken.clientId,name:result.accessToken.name,scopes:result.accessToken.scopes,abilities,expiresAt:result.accessToken.expiresAt??expiresAt,createdAt:result.accessToken.createdAt,updatedAt:result.accessToken.updatedAt,revoked:result.accessToken.revoked,plainTextToken},plainTextToken,refreshToken:result.refreshToken,expiresIn:result.expiresIn}}static async createToken(user,name=config.auth.defaultTokenName||"auth-token",abilities=config.auth.defaultAbilities||["*"]){const{plainTextToken}=await this.createTokenForUser(user,{name,abilities});return plainTextToken}static async requestToken(credentials,clientId,clientSecret){const client=await this.verifiedClient(clientId,clientSecret);if(!client)throw new HttpError(401,"Invalid client credentials");const result=await this.withVerifiedCredentials(credentials,async(user)=>{let currentQuery=db.primary.selectFrom("oauth_clients").where("id","=",client.id).select(["secret","revoked"]);if(getDatabaseDialect()!=="sqlite")currentQuery=currentQuery.sharedLock();const current=await currentQuery.executeTakeFirst();if(!current||current.revoked||current.secret!==client.secret)throw new HttpError(401,"Invalid client credentials");const issued=await this.createTokenForUser(user,{name:"user-auth-token",clientId:client.id});return{user,token:issued.plainTextToken}}),state=authStateOrNull();if(result&&state)state.authUser=result.user;return result?{token:result.token}:null}static async validateToken(token){const hashedPlainToken=hashToken(token),accessToken=await db.primary.selectFrom("oauth_access_tokens").where("token","=",hashedPlainToken).selectAll().executeTakeFirst();if(!accessToken||accessToken.tokenable_type!==DEFAULT_TOKENABLE_TYPE)return!1;log.debug(`[auth] Token validated for token#${accessToken.id}`);if(accessToken.expires_at!=null&&(parseSqlDateTime(accessToken.expires_at)??new Date(0))<=new Date)return!1;if(accessToken.revoked)return!1;if(isIssuedBeforePasswordChange(accessToken.created_at,await getPasswordChangedAt(accessToken.tokenable_id)))return!1;await db.updateTable("oauth_access_tokens").set({updated_at:formatDate(new Date)}).where("id","=",accessToken.id).execute();return!0}static async getUserFromToken(token){const hashedPlainToken=hashToken(token),accessToken=await db.primary.selectFrom("oauth_access_tokens").where("token","=",hashedPlainToken).selectAll().executeTakeFirst();if(!accessToken||accessToken.tokenable_type!==DEFAULT_TOKENABLE_TYPE)return;if(accessToken.expires_at!=null&&(parseSqlDateTime(accessToken.expires_at)??new Date(0))<=new Date)return;if(accessToken.revoked)return;const idleMs=config.auth?.idleTimeout??0;if(idleMs>0){const lastSeen=parseSqlDateTime(accessToken.updated_at??accessToken.created_at);if(lastSeen&&Date.now()-lastSeen.getTime()>idleMs){await db.updateTable("oauth_access_tokens").set({revoked:!0}).where("id","=",accessToken.id).execute();return}}if(!accessToken?.tokenable_id)return;const user=await User.find(accessToken.tokenable_id);if(!user)return;if(isIssuedBeforePasswordChange(accessToken.created_at,await getPasswordChangedAt(accessToken.tokenable_id)))return;const updatedAt=formatDate(new Date);await db.updateTable("oauth_access_tokens").set({updated_at:updatedAt}).where("id","=",accessToken.id).execute();const stateForToken=authStateOrNull();if(stateForToken)stateForToken.currentToken=this.tokenFromRow({...accessToken,updated_at:updatedAt});return user}static async currentAccessToken(){const state=authStateOrNull();if(state?.currentToken){const cached=state.currentToken;if(cached.revoked||cached.expiresAt!=null&&!(cached.expiresAt.getTime()>Date.now()))return;return cached}const bearerToken=this.getBearerToken();if(!bearerToken)return;const accessToken=await db.primary.selectFrom("oauth_access_tokens").where("token","=",hashToken(bearerToken)).selectAll().executeTakeFirst();if(!accessToken||accessToken.tokenable_type!==DEFAULT_TOKENABLE_TYPE||accessToken.revoked)return;if(accessToken.expires_at!=null&&(parseSqlDateTime(accessToken.expires_at)??new Date(0))<=new Date)return;const idleMs=config.auth?.idleTimeout??0,lastSeen=parseSqlDateTime(accessToken.updated_at??accessToken.created_at);if(idleMs>0&&lastSeen&&Date.now()-lastSeen.getTime()>idleMs)return;if(isIssuedBeforePasswordChange(accessToken.created_at,await getPasswordChangedAt(accessToken.tokenable_id)))return;const token=this.tokenFromRow(accessToken);if(state)state.currentToken=token;return token}static async tokenCan(ability){const token=await this.currentAccessToken();if(!token)return!1;if(token.abilities.includes("*"))return!0;return token.abilities.includes(ability)}static async tokenCant(ability){return!await this.tokenCan(ability)}static async tokenAbilities(){return(await this.currentAccessToken())?.abilities??[]}static async tokenCanAll(abilities){const token=await this.currentAccessToken();if(!token)return!1;if(token.abilities.includes("*"))return!0;return abilities.every((a)=>token.abilities.includes(a))}static async tokenCanAny(abilities){const token=await this.currentAccessToken();if(!token)return!1;if(token.abilities.includes("*"))return!0;return abilities.some((a)=>token.abilities.includes(a))}static async tokens(userId){const uid=userId??await this.id();if(!uid)return[];return(await db.primary.selectFrom("oauth_access_tokens").where("tokenable_id","=",uid).where("tokenable_type","=",DEFAULT_TOKENABLE_TYPE).where("revoked","=",!1).selectAll().execute()).map((token)=>({id:Number(token.id),userId:Number(token.user_id),clientId:Number(token.oauth_client_id),name:String(token.name||"auth-token"),scopes:parseScopes(String(token.scopes??"")),abilities:parseScopes(String(token.scopes??"")),expiresAt:token.expires_at==null?null:tokenDate(token.expires_at),...tokenTimestamps(token),revoked:!!token.revoked}))}static async revokeToken(token){await revokeTokenPair({hash:hashToken(token)})}static async revokeTokenById(tokenId){await revokeTokenPair({id:tokenId})}static async revokeAllTokens(userId){const uid=userId??await this.id();if(!uid)return;await revokeTokenPairs(uid,DEFAULT_TOKENABLE_TYPE)}static async revokeOtherTokens(userId){const uid=userId??await this.id();if(!uid)return;const currentToken=await this.currentAccessToken();if(!currentToken)return;await revokeTokenPairs(uid,DEFAULT_TOKENABLE_TYPE,currentToken.id)}static async pruneExpiredTokens(){return deleteExpiredTokens()}static async pruneRevokedTokens(){const result=await db.deleteFrom("oauth_access_tokens").where("revoked","=",!0).executeTakeFirst();return Number(result?.numDeletedRows)||0}static async rotateToken(oldToken){const{findToken:findRawToken,revokeToken:revokeRawToken}=await import("./tokens"),candidate=await findRawToken(oldToken);if(!candidate)return null;return db.transaction(async()=>{let query=db.primary.selectFrom("oauth_access_tokens").where("id","=",candidate.id).selectAll();if(getDatabaseDialect()!=="sqlite")query=query.lockForUpdate();const owner=await query.executeTakeFirst();if(!owner||owner.revoked||owner.tokenable_type!==DEFAULT_TOKENABLE_TYPE)return null;const deadline=parseSqlDateTime(owner.expires_at);if(owner.expires_at!=null&&(!deadline||deadline.getTime()<=Date.now()))return null;const existing=await findRawToken(oldToken);if(!existing||Number(existing.id)!==Number(owner.id))return null;const user=await User.find(Number(owner.tokenable_id));if(!user)return null;await revokeRawToken(oldToken);return(await this.createTokenForUser(user,{name:String(owner.name||"access-token"),abilities:parseScopes(owner.scopes),expiresAt:deadline??new Date(Date.now()+(config.auth.tokenExpiry??3600000)),withRefreshToken:!1})).plainTextToken})}static async findToken(tokenId){return this.getTokenFromId(tokenId)}static async once(credentials){const username=config.auth.username||"email",password=config.auth.password||"password",email=credentials[username];if(!email)return!1;const user=await User.where("email","=",email).first(),authPass=credentials[password]||"",hashToVerify=user?.password||DUMMY_BCRYPT_HASH;if(await verifyHash(authPass,hashToVerify)&&user){const state=authStateOrNull();if(state)state.authUser=user;return!0}return!1}static guard(_name){return this}static viaRemember(){return!1}static clearState(){const state=authStateOrNull();if(state){state.authUser=void 0;state.currentToken=void 0;state.clientSecret=void 0}}}
+import{config}from"@stacksjs/config";import{db,getDatabaseDialect,isInTransaction,parseSqlDateTime}from"@stacksjs/database/runtime";import{HttpError}from"@stacksjs/error-handling";import{formatDate,User}from"@stacksjs/orm";import{getCurrentRequest,request}from"@stacksjs/router";import{requestToken}from"./request-token";import{sessionLogout,sessionUser}from"./session-auth";import{revokeTokenPair,revokeTokenPairs}from"./token-revocation";import{Buffer}from"node:buffer";import{createHash,timingSafeEqual}from"node:crypto";import{decrypt,encrypt,verifyHash}from"@stacksjs/security";import{log}from"@stacksjs/logging";import{DUMMY_BCRYPT_HASH}from"./internal-constants";import{RateLimiter}from"./rate-limiter";import{withVerifiedPassword}from"./credential-version";import{tokenDate,tokenTimestamps}from"./token-dates";import{schedulePasswordRehash}from"./password-rehash";const REQUEST_AUTH_STATE_KEY=Symbol.for("stacks.requestAuthState");function authStateOrNull(){const req=getCurrentRequest();if(!req)return null;let state=req[REQUEST_AUTH_STATE_KEY];if(!state){state={};req[REQUEST_AUTH_STATE_KEY]=state}return state}function hashToken(token){return createHash("sha256").update(token).digest("hex")}import{createToken as createRawToken,DEFAULT_TOKENABLE_TYPE,deleteExpiredTokens,getPasswordChangedAt,isIssuedBeforePasswordChange,parseScopes}from"./tokens";export class Auth{static getBearerToken(){return requestToken(request)}static parseToken(token){const firstColonIndex=token.indexOf(":");if(firstColonIndex===-1)return null;const plainToken=token.substring(0,firstColonIndex),encryptedId=token.substring(firstColonIndex+1);if(!plainToken||!encryptedId)return null;return{plainToken,encryptedId}}static async getClientSecret(){const state=authStateOrNull();if(state?.clientSecret)return state.clientSecret;const client=await this.getPersonalAccessClient();if(state)state.clientSecret=client.secret;return client.secret}static async encryptTokenId(id){return await encrypt(String(id))}static async decryptTokenId(encryptedId){try{return await decrypt(encryptedId)}catch{try{const clientSecret=await this.getClientSecret();return await decrypt(encryptedId,clientSecret)}catch{return null}}}static async getPersonalAccessClient(){try{const client=await db.primary.selectFrom("oauth_clients").where("personal_access_client","=",!0).where("revoked","=",!1).selectAll().executeTakeFirst();if(!client)throw new HttpError(500,"No personal access client found. Please run `./buddy auth:setup` first.");return client}catch(error){if(error instanceof Error&&error.message.includes("does not exist"))throw new HttpError(500,"OAuth tables not found. Please run `./buddy auth:setup` first.");throw error}}static async verifiedClient(clientId,clientSecret){const client=await db.primary.selectFrom("oauth_clients").where("id","=",clientId).where("revoked","=",!1).selectAll().executeTakeFirst(),provided=Buffer.from(clientSecret);if(!client?.secret){const dummy=Buffer.alloc(Math.max(provided.length,1)),padded=provided.length>0?provided:Buffer.alloc(1);timingSafeEqual(dummy,padded);return null}const stored=String(client.secret);if(stored.startsWith("$2"))return await verifyHash(clientSecret,stored)?client:null;const storedBuf=Buffer.from(stored);if(storedBuf.length!==provided.length){timingSafeEqual(storedBuf,storedBuf);return null}return timingSafeEqual(storedBuf,provided)?client:null}static async getTokenFromId(tokenId){const result=await db.primary.selectFrom("oauth_access_tokens").where("id","=",tokenId).selectAll().executeTakeFirst();if(!result)return null;return this.tokenFromRow(result)}static tokenFromRow(token){return{id:token.id,userId:token.user_id,clientId:token.oauth_client_id,name:token.name||"auth-token",scopes:parseScopes(token.scopes),abilities:parseScopes(token.scopes),expiresAt:token.expires_at==null?null:tokenDate(token.expires_at),...tokenTimestamps(token),revoked:!!token.revoked}}static async attempt(credentials){const verified=await this.verifyCredentials(credentials);if(!verified)return!1;schedulePasswordRehash(verified.user.id,verified.plaintext,verified.hash);const state=authStateOrNull();if(state)state.authUser=verified.user;return!0}static async verifyCredentials(credentials){const username=config.auth.username||"email",password=config.auth.password||"password",email=credentials[username];if(!email)return null;const isRateLimited=await RateLimiter.isRateLimited(email),user=await User.where("email","=",email).first(),authPass=credentials[password]||"",hashToVerify=user?.password||DUMMY_BCRYPT_HASH,hashCheck=await verifyHash(authPass,hashToVerify);if(isRateLimited)return null;if(hashCheck&&user){await RateLimiter.resetAttempts(email);return{user,plaintext:authPass,hash:hashToVerify}}await RateLimiter.recordFailedAttempt(email);return null}static async validate(credentials){const username=config.auth.username||"email",password=config.auth.password||"password",email=credentials[username];if(!email)return!1;const user=await User.where("email","=",email).first(),authPass=credentials[password]||"",hashToVerify=user?.password||DUMMY_BCRYPT_HASH;return await verifyHash(authPass,hashToVerify)&&!!user}static async withVerifiedCredentials(credentials,issue){const verified=await this.verifyCredentials(credentials);if(!verified)return null;const result=await withVerifiedPassword(verified.user.id,verified.hash,()=>issue(verified.user));if(result!==null)schedulePasswordRehash(verified.user.id,verified.plaintext,verified.hash);return result}static async login(credentials,options){const result=await this.withVerifiedCredentials(credentials,async(user)=>{const{plainTextToken,refreshToken,expiresIn}=await this.createTokenForUser(user,options);return{user,token:plainTextToken,refreshToken,expiresIn}});if(!result)return null;const state=authStateOrNull();if(state)state.authUser=result.user;return result}static async loginUsingId(userId,options){let user;if(isInTransaction()){const definition=User.getDefinition();let query=db.primary.selectFrom(definition.table||"users").where(definition.primaryKey||"id","=",userId).selectAll();if(definition.traits?.useSoftDeletes)query=query.whereNull("deleted_at");const row=await query.executeTakeFirst();user=row?await User.make(row):null}else user=await User.find(userId);if(!user)return null;const state=authStateOrNull(),{plainTextToken,refreshToken,expiresIn}=await this.createTokenForUser(user,options);if(state)state.authUser=user;return{user,token:plainTextToken,refreshToken,expiresIn}}static async logout(){const bearerToken=this.getBearerToken();if(bearerToken)await this.revokeToken(bearerToken);else{const sessionId=getCurrentRequest()?.cookie?.("session_id");if(sessionId)await sessionLogout(sessionId)}const state=authStateOrNull();if(state){state.authUser=void 0;state.currentToken=void 0}const currentRequest=getCurrentRequest();if(currentRequest){currentRequest._authenticatedUser=void 0;currentRequest._currentAccessToken=void 0}}static async user(){const state=authStateOrNull();if(state?.authUser)return state.authUser;const bearerToken=this.getBearerToken(),sessionId=!bearerToken?getCurrentRequest()?.cookie?.("session_id"):void 0,user=bearerToken?await this.getUserFromToken(bearerToken):sessionId?await sessionUser(sessionId):void 0;if(user&&state)state.authUser=user;return user}static async check(){return await this.user()!==void 0}static async guest(){return!await this.check()}static async id(){return(await this.user())?.id}static setUser(user){const state=authStateOrNull();if(state)state.authUser=user}static async createTokenForUser(user,options){const name=options?.name??config.auth.defaultTokenName??"auth-token",abilities=options?.abilities??options?.scopes??config.auth.defaultAbilities??["*"],accessTtlMs=options?.expiresInMinutes!==void 0?options.expiresInMinutes*60*1000:config.auth.tokenExpiry??3600000,expiresAt=new Date(options?.expiresAt?.getTime()??Date.now()+accessTtlMs),refreshExpiresInDays=options?.refreshExpiresInDays??Math.max(1,Math.round((config.auth.refreshTokenExpiry??2592000000)/86400000));log.debug(`[auth] Creating token for user#${user.id}: ${name}`);const result=await createRawToken(user.id,name,abilities,{expiresAt,clientId:options?.clientId,withRefreshToken:options?.withRefreshToken!==!1,refreshExpiresInDays,userAgent:options?.userAgent??null,ipAddress:options?.ipAddress??null}),plainTextToken=result.plainTextToken;return{accessToken:{id:result.accessToken.id,userId:result.accessToken.userId,clientId:result.accessToken.clientId,name:result.accessToken.name,scopes:result.accessToken.scopes,abilities,expiresAt:result.accessToken.expiresAt??expiresAt,createdAt:result.accessToken.createdAt,updatedAt:result.accessToken.updatedAt,revoked:result.accessToken.revoked,plainTextToken},plainTextToken,refreshToken:result.refreshToken,expiresIn:result.expiresIn}}static async createToken(user,name=config.auth.defaultTokenName||"auth-token",abilities=config.auth.defaultAbilities||["*"]){const{plainTextToken}=await this.createTokenForUser(user,{name,abilities});return plainTextToken}static async requestUserTokenWithClient(credentials,clientId,clientSecret){const client=await this.verifiedClient(clientId,clientSecret);if(!client)throw new HttpError(401,"Invalid client credentials");const result=await this.withVerifiedCredentials(credentials,async(user)=>{let currentQuery=db.primary.selectFrom("oauth_clients").where("id","=",client.id).select(["secret","revoked"]);if(getDatabaseDialect()!=="sqlite")currentQuery=currentQuery.sharedLock();const current=await currentQuery.executeTakeFirst();if(!current||current.revoked||current.secret!==client.secret)throw new HttpError(401,"Invalid client credentials");const issued=await this.createTokenForUser(user,{name:"user-auth-token",clientId:client.id});return{user,token:issued.plainTextToken}}),state=authStateOrNull();if(result&&state)state.authUser=result.user;return result?{token:result.token}:null}static async requestToken(credentials,clientId,clientSecret){return this.requestUserTokenWithClient(credentials,clientId,clientSecret)}static async validateToken(token){const hashedPlainToken=hashToken(token),accessToken=await db.primary.selectFrom("oauth_access_tokens").where("token","=",hashedPlainToken).selectAll().executeTakeFirst();if(!accessToken||accessToken.tokenable_type!==DEFAULT_TOKENABLE_TYPE)return!1;log.debug(`[auth] Token validated for token#${accessToken.id}`);if(accessToken.expires_at!=null&&(parseSqlDateTime(accessToken.expires_at)??new Date(0))<=new Date)return!1;if(accessToken.revoked)return!1;if(isIssuedBeforePasswordChange(accessToken.created_at,await getPasswordChangedAt(accessToken.tokenable_id)))return!1;await db.updateTable("oauth_access_tokens").set({updated_at:formatDate(new Date)}).where("id","=",accessToken.id).execute();return!0}static async getUserFromToken(token){const hashedPlainToken=hashToken(token),accessToken=await db.primary.selectFrom("oauth_access_tokens").where("token","=",hashedPlainToken).selectAll().executeTakeFirst();if(!accessToken||accessToken.tokenable_type!==DEFAULT_TOKENABLE_TYPE)return;if(accessToken.expires_at!=null&&(parseSqlDateTime(accessToken.expires_at)??new Date(0))<=new Date)return;if(accessToken.revoked)return;const idleMs=config.auth?.idleTimeout??0;if(idleMs>0){const lastSeen=parseSqlDateTime(accessToken.updated_at??accessToken.created_at);if(lastSeen&&Date.now()-lastSeen.getTime()>idleMs){await db.updateTable("oauth_access_tokens").set({revoked:!0}).where("id","=",accessToken.id).execute();return}}if(!accessToken?.tokenable_id)return;const user=await User.find(accessToken.tokenable_id);if(!user)return;if(isIssuedBeforePasswordChange(accessToken.created_at,await getPasswordChangedAt(accessToken.tokenable_id)))return;const updatedAt=formatDate(new Date);await db.updateTable("oauth_access_tokens").set({updated_at:updatedAt}).where("id","=",accessToken.id).execute();const stateForToken=authStateOrNull();if(stateForToken)stateForToken.currentToken=this.tokenFromRow({...accessToken,updated_at:updatedAt});return user}static async currentAccessToken(){const state=authStateOrNull();if(state?.currentToken){const cached=state.currentToken;if(cached.revoked||cached.expiresAt!=null&&!(cached.expiresAt.getTime()>Date.now()))return;return cached}const bearerToken=this.getBearerToken();if(!bearerToken)return;const accessToken=await db.primary.selectFrom("oauth_access_tokens").where("token","=",hashToken(bearerToken)).selectAll().executeTakeFirst();if(!accessToken||accessToken.tokenable_type!==DEFAULT_TOKENABLE_TYPE||accessToken.revoked)return;if(accessToken.expires_at!=null&&(parseSqlDateTime(accessToken.expires_at)??new Date(0))<=new Date)return;const idleMs=config.auth?.idleTimeout??0,lastSeen=parseSqlDateTime(accessToken.updated_at??accessToken.created_at);if(idleMs>0&&lastSeen&&Date.now()-lastSeen.getTime()>idleMs)return;if(isIssuedBeforePasswordChange(accessToken.created_at,await getPasswordChangedAt(accessToken.tokenable_id)))return;const token=this.tokenFromRow(accessToken);if(state)state.currentToken=token;return token}static async tokenCan(ability){const token=await this.currentAccessToken();if(!token)return!1;if(token.abilities.includes("*"))return!0;return token.abilities.includes(ability)}static async tokenCant(ability){return!await this.tokenCan(ability)}static async tokenAbilities(){return(await this.currentAccessToken())?.abilities??[]}static async tokenCanAll(abilities){const token=await this.currentAccessToken();if(!token)return!1;if(token.abilities.includes("*"))return!0;return abilities.every((a)=>token.abilities.includes(a))}static async tokenCanAny(abilities){const token=await this.currentAccessToken();if(!token)return!1;if(token.abilities.includes("*"))return!0;return abilities.some((a)=>token.abilities.includes(a))}static async tokens(userId){const uid=userId??await this.id();if(!uid)return[];return(await db.primary.selectFrom("oauth_access_tokens").where("tokenable_id","=",uid).where("tokenable_type","=",DEFAULT_TOKENABLE_TYPE).where("revoked","=",!1).selectAll().execute()).map((token)=>({id:Number(token.id),userId:Number(token.user_id),clientId:Number(token.oauth_client_id),name:String(token.name||"auth-token"),scopes:parseScopes(String(token.scopes??"")),abilities:parseScopes(String(token.scopes??"")),expiresAt:token.expires_at==null?null:tokenDate(token.expires_at),...tokenTimestamps(token),revoked:!!token.revoked}))}static async revokeToken(token){await revokeTokenPair({hash:hashToken(token)})}static async revokeTokenById(tokenId){await revokeTokenPair({id:tokenId})}static async revokeAllTokens(userId){const uid=userId??await this.id();if(!uid)return;await revokeTokenPairs(uid,DEFAULT_TOKENABLE_TYPE)}static async revokeOtherTokens(userId){const uid=userId??await this.id();if(!uid)return;const currentToken=await this.currentAccessToken();if(!currentToken)return;await revokeTokenPairs(uid,DEFAULT_TOKENABLE_TYPE,currentToken.id)}static async pruneExpiredTokens(){return deleteExpiredTokens()}static async pruneRevokedTokens(){const result=await db.deleteFrom("oauth_access_tokens").where("revoked","=",!0).executeTakeFirst();return Number(result?.numDeletedRows)||0}static async rotateToken(oldToken){const{findToken:findRawToken,revokeToken:revokeRawToken}=await import("./tokens"),candidate=await findRawToken(oldToken);if(!candidate)return null;return db.transaction(async()=>{let query=db.primary.selectFrom("oauth_access_tokens").where("id","=",candidate.id).selectAll();if(getDatabaseDialect()!=="sqlite")query=query.lockForUpdate();const owner=await query.executeTakeFirst();if(!owner||owner.revoked||owner.tokenable_type!==DEFAULT_TOKENABLE_TYPE)return null;const deadline=parseSqlDateTime(owner.expires_at);if(owner.expires_at!=null&&(!deadline||deadline.getTime()<=Date.now()))return null;const existing=await findRawToken(oldToken);if(!existing||Number(existing.id)!==Number(owner.id))return null;const user=await User.find(Number(owner.tokenable_id));if(!user)return null;await revokeRawToken(oldToken);return(await this.createTokenForUser(user,{name:String(owner.name||"access-token"),abilities:parseScopes(owner.scopes),expiresAt:deadline??new Date(Date.now()+(config.auth.tokenExpiry??3600000)),withRefreshToken:!1})).plainTextToken})}static async findToken(tokenId){return this.getTokenFromId(tokenId)}static async once(credentials){const username=config.auth.username||"email",password=config.auth.password||"password",email=credentials[username];if(!email)return!1;const user=await User.where("email","=",email).first(),authPass=credentials[password]||"",hashToVerify=user?.password||DUMMY_BCRYPT_HASH;if(await verifyHash(authPass,hashToVerify)&&user){const state=authStateOrNull();if(state)state.authUser=user;return!0}return!1}static guard(_name){return this}static viaRemember(){return!1}static clearState(){const state=authStateOrNull();if(state){state.authUser=void 0;state.currentToken=void 0;state.clientSecret=void 0}}}

package/dist/index.d.ts

@@ -3,6 +3,20 @@ export * from './authentication';
 export * from './authenticator';
 export * from './client';
 export * from './middleware';
+export * from './oauth-authorization';
+export * from './oauth-authorization-requests';
+export * from './oauth-authorization-codes';
+export * from './oauth-client-registration';
+export * from './oauth-consent';
+export * from './oauth-delegated-access';
+export * from './oauth-grants';
+export * from './oauth-provider';
+export * from './oauth-pkce';
+export * from './oauth-revocation';
+export * from './oauth-token-exchange';
+export * from './oauth-token-endpoint';
+export * from './oauth-token-request';
+export * from './oauth-token-response';
 export * from './rate-limiter';
 // WebAuthn/Passkey support (now using ts-auth - no external dependencies)
 export * from './magic-link';

package/dist/index.js

@@ -1 +1 @@
-export*from"./authentication";export*from"./authenticator";export*from"./client";export*from"./middleware";export*from"./rate-limiter";export*from"./magic-link";export*from"./passkey";export*from"./password/reset";export*from"./register";export*from"./user";export*from"./tokens";export*from"./gate";export*from"./policy";export*from"./authorizable";export*from"./permissions";export*from"./rbac";export{createBqbRbacStore}from"./rbac-store-bqb";export{DEFAULT_ROLE_PACKS,seedDefaultRoles}from"./rbac-seed";export*from"./email-verification";export*from"./session-auth";export*from"./cookie-auth";export*from"./browser-session";export*from"./request-token";export*from"./page-gate";export*from"./socials";export{generateTOTP,verifyTOTP,generateTOTPSecret,totpKeyUri}from"@stacksjs/ts-auth";export*from"./two-factor";export*from"./team";export*from"./referrals";
+export*from"./authentication";export*from"./authenticator";export*from"./client";export*from"./middleware";export*from"./oauth-authorization";export*from"./oauth-authorization-requests";export*from"./oauth-authorization-codes";export*from"./oauth-client-registration";export*from"./oauth-consent";export*from"./oauth-delegated-access";export*from"./oauth-grants";export*from"./oauth-provider";export*from"./oauth-pkce";export*from"./oauth-revocation";export*from"./oauth-token-exchange";export*from"./oauth-token-endpoint";export*from"./oauth-token-request";export*from"./oauth-token-response";export*from"./rate-limiter";export*from"./magic-link";export*from"./passkey";export*from"./password/reset";export*from"./register";export*from"./user";export*from"./tokens";export*from"./gate";export*from"./policy";export*from"./authorizable";export*from"./permissions";export*from"./rbac";export{createBqbRbacStore}from"./rbac-store-bqb";export{DEFAULT_ROLE_PACKS,seedDefaultRoles}from"./rbac-seed";export*from"./email-verification";export*from"./session-auth";export*from"./cookie-auth";export*from"./browser-session";export*from"./request-token";export*from"./page-gate";export*from"./socials";export{generateTOTP,verifyTOTP,generateTOTPSecret,totpKeyUri}from"@stacksjs/ts-auth";export*from"./two-factor";export*from"./team";export*from"./referrals";

package/dist/oauth-authorization-codes.d.ts

@@ -0,0 +1,32 @@
+/** Issue a high-entropy code while storing only its SHA-256 hash. */
+export declare function issueAuthorizationCode(input: IssueAuthorizationCodeInput): Promise<string>;
+/**
+ * Claim one code and complete credential issuance in the same transaction.
+ * A failed completion rolls the claim back so an infrastructure failure does
+ * not strand a valid grant. Concurrent successful commits remain single-use.
+ */
+export declare function withAuthorizationCode<T>(rawCode: string, expected: AuthorizationCodeRedemption, complete: (grant: AuthorizationCodeGrant) => Promise<T>): Promise<AuthorizationCodeResult<T>>;
+export declare interface IssueAuthorizationCodeInput {
+  grantId: string
+  redirectUri: string
+  codeChallenge: string
+  lifetimeMs: number
+}
+export declare interface AuthorizationCodeRedemption {
+  clientId: number
+  redirectUri: string
+  codeVerifier: string
+}
+export declare interface AuthorizationCodeGrant {
+  grantId: string
+  clientId: number
+  subjectType: string
+  subjectId: number
+  redirectUri: string
+  scopes: string[]
+  resources: string[]
+  audiences: string[]
+  workspaceId: string | null
+}
+export type AuthorizationCodeResult<T> = | { ok: true, value: T }
+    | { ok: false, reason: 'invalid_grant' }

package/dist/oauth-authorization-codes.js

@@ -0,0 +1,29 @@
+import{createHash,randomBytes}from"node:crypto";import{db,getDatabaseDialect,markContextWrote,mutationCount,parseSqlDateTime,sqlDateTime,sqlHelpers}from"@stacksjs/database/runtime";import{isValidOAuthRedirectUri}from"./oauth-authorization";import{isValidS256CodeChallenge,verifyS256CodeChallenge}from"./oauth-pkce";const invalidGrant={ok:!1,reason:"invalid_grant"},AUTHORIZATION_CODE_PATTERN=/^[A-Za-z0-9_-]{43}$/;function codeHash(value){return createHash("sha256").update(value,"ascii").digest("hex")}function validIdentifier(value){return Number.isSafeInteger(value)&&value>0}function storedValues(value){try{const parsed=JSON.parse(value);return Array.isArray(parsed)&&parsed.every((item)=>typeof item==="string")?parsed:null}catch{return null}}export async function issueAuthorizationCode(input){if(!/^[a-f0-9]{32}$/.test(input.grantId))throw TypeError("OAuth authorization code grant identifier is invalid.");if(!isValidOAuthRedirectUri(input.redirectUri))throw TypeError("OAuth authorization code redirect URI is invalid.");if(!isValidS256CodeChallenge(input.codeChallenge))throw TypeError("OAuth authorization code requires a valid S256 challenge.");if(!Number.isFinite(input.lifetimeMs)||input.lifetimeMs<=0)throw TypeError("OAuth authorization code lifetime must be positive.");const plainTextCode=randomBytes(32).toString("base64url"),createdAt=new Date,sql=sqlHelpers(getDatabaseDialect());await db.transaction(async(rawTrx)=>{const trx=rawTrx,grantLock=sql.isPostgres?" FOR SHARE":sql.isMysql?" LOCK IN SHARE MODE":"",grant=(await trx.unsafe(`
+      SELECT id, client_id, subject_type, subject_id, scopes, resources, audiences, workspace_id
+      FROM oauth_grants
+      WHERE id = ${sql.param(1)} AND revoked_at IS NULL
+      LIMIT 1${grantLock}
+    `,[input.grantId]))[0];if(!grant)throw Error("OAuth authorization grant is not active.");const bound=sql.params(codeHash(plainTextCode),input.grantId,grant.client_id,grant.subject_type,grant.subject_id,input.redirectUri,grant.scopes,grant.resources,grant.audiences,grant.workspace_id??null,input.codeChallenge,"S256",sqlDateTime(new Date(createdAt.getTime()+input.lifetimeMs)),sqlDateTime(createdAt));await trx.unsafe(`
+      INSERT INTO oauth_auth_codes (
+        code_hash, grant_id, client_id, subject_type, subject_id, redirect_uri, scopes, resources,
+        audiences, workspace_id, code_challenge, code_challenge_method, expires_at, created_at
+      ) VALUES (${bound.sql})
+    `,bound.values)});markContextWrote();return plainTextCode}export async function withAuthorizationCode(rawCode,expected,complete){if(!AUTHORIZATION_CODE_PATTERN.test(rawCode)||!validIdentifier(expected.clientId))return invalidGrant;const sql=sqlHelpers(getDatabaseDialect()),hash=codeHash(rawCode),lock=sql.isSqlite?"":" FOR UPDATE",result=await db.transaction(async(rawTrx)=>{const trx=rawTrx,row=(await trx.unsafe(`
+      SELECT c.code_hash, c.grant_id, c.client_id, c.subject_type, c.subject_id, c.redirect_uri,
+        c.scopes, c.resources, c.audiences, c.workspace_id, c.code_challenge,
+        c.code_challenge_method, c.expires_at, c.consumed_at,
+        g.client_id AS grant_client_id, g.subject_type AS grant_subject_type,
+        g.subject_id AS grant_subject_id, g.scopes AS grant_scopes,
+        g.resources AS grant_resources, g.audiences AS grant_audiences,
+        g.workspace_id AS grant_workspace_id
+      FROM oauth_auth_codes c
+      JOIN oauth_grants g ON g.id = c.grant_id AND g.revoked_at IS NULL
+      WHERE c.code_hash = ${sql.param(1)}
+      LIMIT 1${lock}
+    `,[hash]))[0];if(!row||row.consumed_at!=null||String(row.client_id)!==String(expected.clientId)||row.redirect_uri!==expected.redirectUri||row.code_challenge_method!=="S256"||(parseSqlDateTime(row.expires_at)?.getTime()??0)<=Date.now()||!await verifyS256CodeChallenge(expected.codeVerifier,row.code_challenge))return invalidGrant;const scopes=storedValues(row.scopes),resources=storedValues(row.resources),audiences=storedValues(row.audiences),grantScopes=storedValues(row.grant_scopes),grantResources=storedValues(row.grant_resources),grantAudiences=storedValues(row.grant_audiences),clientId=Number(row.client_id),subjectId=Number(row.subject_id);if(!row.grant_id||!scopes||!resources||!audiences||!grantScopes||!grantResources||!grantAudiences||!validIdentifier(clientId)||!validIdentifier(subjectId)||String(row.grant_client_id)!==String(row.client_id)||row.grant_subject_type!==row.subject_type||String(row.grant_subject_id)!==String(row.subject_id)||JSON.stringify(grantScopes)!==JSON.stringify(scopes)||JSON.stringify(grantResources)!==JSON.stringify(resources)||JSON.stringify(grantAudiences)!==JSON.stringify(audiences)||row.grant_workspace_id!==row.workspace_id)return invalidGrant;const now=sqlDateTime(new Date),claimed=await trx.unsafe(`
+      UPDATE oauth_auth_codes
+      SET consumed_at = ${sql.param(1)}
+      WHERE code_hash = ${sql.param(2)}
+        AND consumed_at IS NULL
+        AND expires_at > ${sql.param(3)}
+    `,[now,hash,now]);if(mutationCount(claimed)!==1)return invalidGrant;return{ok:!0,value:await complete({grantId:row.grant_id,clientId,subjectType:row.subject_type,subjectId,redirectUri:row.redirect_uri,scopes,resources,audiences,workspaceId:row.workspace_id})}});if(result.ok)markContextWrote();return result}

package/dist/oauth-authorization-requests.d.ts

@@ -0,0 +1,9 @@
+import type { ValidatedOAuthAuthorizationRequest } from './oauth-authorization';
+/** Store one validated authorization request behind an opaque, hashed handle. */
+export declare function createOAuthAuthorizationRequestSession(request: ValidatedOAuthAuthorizationRequest, browserSessionId: string, lifetimeMs: number): Promise<string>;
+/** Reload a request only for its original browser and current client policy. */
+export declare function loadOAuthAuthorizationRequestSession(requestId: string, browserSessionId: string): Promise<ValidatedOAuthAuthorizationRequest | null>;
+/** Claim one browser-bound request and complete consent in the same transaction. */
+export declare function withOAuthAuthorizationRequestSession<T>(requestId: string, browserSessionId: string, complete: (request: ValidatedOAuthAuthorizationRequest) => Promise<T>): Promise<OAuthAuthorizationRequestSessionResult<T>>;
+export type OAuthAuthorizationRequestSessionResult<T> = | { ok: true, value: T }
+    | { ok: false, reason: 'invalid_request' }

package/dist/oauth-authorization-requests.js

@@ -0,0 +1,37 @@
+import{createHash,randomBytes}from"node:crypto";import{db,getDatabaseDialect,markContextWrote,mutationCount,parseSqlDateTime,sqlDateTime,sqlHelpers}from"@stacksjs/database/runtime";import{isValidOAuthRedirectUri}from"./oauth-authorization";import{loadOAuthAuthorizationClient}from"./oauth-client-registration";import{isValidS256CodeChallenge}from"./oauth-pkce";const REQUEST_ID_PATTERN=/^[A-Za-z0-9_-]{43}$/,invalidRequest={ok:!1,reason:"invalid_request"};function requestHash(value){return createHash("sha256").update(value,"ascii").digest("hex")}function browserSessionHash(value){return createHash("sha256").update(value,"utf8").digest("hex")}function validBrowserSession(value){return value.length>=16&&value.length<=4096}function storedValues(value){if(value==null)return null;try{const parsed=JSON.parse(value);return Array.isArray(parsed)&&parsed.every((item)=>typeof item==="string")?parsed:null}catch{return null}}function includesAll(allowed,requested){return requested.every((value)=>allowed.includes(value))}function inactive(value){return value===!1||value===0}function requestFromStoredRow(row,now){const clientId=Number(row.client_id);if(!Number.isSafeInteger(clientId)||clientId<=0||row.client_type!=="public"&&row.client_type!=="confidential"||!isValidOAuthRedirectUri(row.redirect_uri)||row.code_challenge_method!=="S256"||!isValidS256CodeChallenge(row.code_challenge)||(parseSqlDateTime(row.expires_at)?.getTime()??0)<=now||row.consumed_at!=null||row.state!=null&&row.state.length>4096)return null;const scopes=storedValues(row.scopes),resources=storedValues(row.resources),audiences=storedValues(row.audiences);if(!scopes||!resources||!audiences||resources.length!==audiences.length)return null;return{responseType:"code",clientId:String(clientId),clientType:row.client_type,redirectUri:row.redirect_uri,scopes,resources,audiences,state:row.state,codeChallenge:row.code_challenge,codeChallengeMethod:"S256"}}function policyAllowsRequest(row,request){if(!row||String(row.id)!==request.clientId)return!1;const redirectUris=storedValues(row.redirect_uris),grantTypes=storedValues(row.grant_types),scopes=storedValues(row.allowed_scopes),resources=storedValues(row.allowed_resources),method=row.token_endpoint_auth_method;if(!redirectUris?.length||!grantTypes?.includes("authorization_code")||!scopes?.length||!resources)return!1;return row.client_type===request.clientType&&inactive(row.revoked)&&inactive(row.personal_access_client)&&inactive(row.password_client)&&(row.client_type==="public"&&method==="none"&&row.secret==null||row.client_type==="confidential"&&method==="client_secret_basic"&&Boolean(row.secret))&&redirectUris.includes(request.redirectUri)&&row.redirect===redirectUris[0]&&new Set(redirectUris).size===redirectUris.length&&new Set(grantTypes).size===grantTypes.length&&new Set(scopes).size===scopes.length&&new Set(resources).size===resources.length&&redirectUris.every(isValidOAuthRedirectUri)&&includesAll(scopes,request.scopes)&&includesAll(resources,request.resources)}export async function createOAuthAuthorizationRequestSession(request,browserSessionId,lifetimeMs){const clientId=Number(request.clientId);if(!Number.isSafeInteger(clientId)||clientId<=0)throw TypeError("OAuth authorization request client identifier is invalid.");if(!validBrowserSession(browserSessionId))throw TypeError("OAuth authorization request requires a valid browser session identifier.");if(!Number.isSafeInteger(lifetimeMs)||lifetimeMs<=0)throw TypeError("OAuth authorization request lifetime must be a positive safe integer.");if(request.state!=null&&request.state.length>4096)throw TypeError("OAuth authorization request state exceeds 4096 characters.");if(!isValidOAuthRedirectUri(request.redirectUri)||!isValidS256CodeChallenge(request.codeChallenge)||request.codeChallengeMethod!=="S256"||request.resources.length!==request.audiences.length)throw TypeError("OAuth authorization request is invalid.");const registered=await loadOAuthAuthorizationClient(request.clientId);if(!registered||registered.revoked||registered.type!==request.clientType||!registered.redirectUris.includes(request.redirectUri)||!registered.grantTypes.includes("authorization_code")||!includesAll(registered.scopes,request.scopes)||!includesAll(registered.resources,request.resources))throw Error("OAuth client registration no longer authorizes this request.");const id=randomBytes(32).toString("base64url"),createdAt=new Date,expiresAt=new Date(createdAt.getTime()+lifetimeMs);if(!Number.isFinite(expiresAt.getTime()))throw TypeError("OAuth authorization request lifetime is outside the supported date range.");const sql=sqlHelpers(getDatabaseDialect());if(sql.isMysql){createdAt.setUTCMilliseconds(0);expiresAt.setUTCMilliseconds(0)}if(expiresAt.getTime()<=createdAt.getTime())throw TypeError("OAuth authorization request lifetime is below database timestamp precision.");const values=sql.params(requestHash(id),browserSessionHash(browserSessionId),clientId,request.clientType,request.redirectUri,JSON.stringify(request.scopes),JSON.stringify(request.resources),JSON.stringify(request.audiences),request.state,request.codeChallenge,request.codeChallengeMethod,sqlDateTime(expiresAt),sqlDateTime(createdAt));await db.unsafe(`
+    INSERT INTO oauth_authorization_requests (
+      request_hash, browser_session_hash, client_id, client_type, redirect_uri,
+      scopes, resources, audiences, state, code_challenge, code_challenge_method,
+      expires_at, created_at
+    ) VALUES (${values.sql})
+  `,values.values);markContextWrote();return id}export async function loadOAuthAuthorizationRequestSession(requestId,browserSessionId){if(!REQUEST_ID_PATTERN.test(requestId)||!validBrowserSession(browserSessionId))return null;const sql=sqlHelpers(getDatabaseDialect()),row=(await db.primary.unsafe(`
+    SELECT client_id, client_type, redirect_uri, scopes, resources, audiences,
+      state, code_challenge, code_challenge_method, expires_at, consumed_at
+    FROM oauth_authorization_requests
+    WHERE request_hash = ${sql.param(1)}
+      AND browser_session_hash = ${sql.param(2)}
+      AND consumed_at IS NULL
+      AND expires_at > ${sql.param(3)}
+    LIMIT 1
+  `,[requestHash(requestId),browserSessionHash(browserSessionId),sqlDateTime(new Date)]))[0];if(!row)return null;const request=requestFromStoredRow(row,Date.now()),registered=await loadOAuthAuthorizationClient(String(row.client_id));if(!request||!registered||registered.revoked||registered.type!==request.clientType||!registered.redirectUris.includes(request.redirectUri)||!registered.grantTypes.includes("authorization_code")||!includesAll(registered.scopes,request.scopes)||!includesAll(registered.resources,request.resources))return null;return request}export async function withOAuthAuthorizationRequestSession(requestId,browserSessionId,complete){if(!REQUEST_ID_PATTERN.test(requestId)||!validBrowserSession(browserSessionId))return invalidRequest;const sql=sqlHelpers(getDatabaseDialect()),hash=requestHash(requestId),sessionHash=browserSessionHash(browserSessionId),requestLock=sql.isSqlite?"":" FOR UPDATE",clientLock=sql.isPostgres?" FOR SHARE":sql.isMysql?" LOCK IN SHARE MODE":"",result=await db.transaction(async(rawTrx)=>{const trx=rawTrx,now=new Date,nowSql=sqlDateTime(now),rows=await trx.unsafe(`
+      SELECT client_id, client_type, redirect_uri, scopes, resources, audiences,
+        state, code_challenge, code_challenge_method, expires_at, consumed_at
+      FROM oauth_authorization_requests
+      WHERE request_hash = ${sql.param(1)}
+        AND browser_session_hash = ${sql.param(2)}
+      LIMIT 1${requestLock}
+    `,[hash,sessionHash]),request=rows[0]?requestFromStoredRow(rows[0],now.getTime()):null;if(!request)return invalidRequest;const clients=await trx.unsafe(`
+      SELECT id, secret, redirect, client_type, redirect_uris, grant_types,
+        token_endpoint_auth_method, allowed_scopes, allowed_resources,
+        personal_access_client, password_client, revoked
+      FROM oauth_clients
+      WHERE id = ${sql.param(1)}
+      LIMIT 1${clientLock}
+    `,[Number(request.clientId)]);if(!policyAllowsRequest(clients[0],request))return invalidRequest;const claimed=await trx.unsafe(`
+      UPDATE oauth_authorization_requests
+      SET consumed_at = ${sql.param(1)}
+      WHERE request_hash = ${sql.param(2)}
+        AND browser_session_hash = ${sql.param(3)}
+        AND consumed_at IS NULL
+        AND expires_at > ${sql.param(4)}
+    `,[nowSql,hash,sessionHash,nowSql]);if(mutationCount(claimed)!==1)return invalidRequest;return{ok:!0,value:await complete(request)}});if(result.ok)markContextWrote();return result}

package/dist/oauth-authorization.d.ts

@@ -0,0 +1,55 @@
+import type { ResolvedOAuthProviderConfig } from './oauth-provider';
+/** Whether a registered callback is safe for exact redirect matching. */
+export declare function isValidOAuthRedirectUri(value: string): boolean;
+/**
+ * Validate the complete, browser-facing authorization request boundary.
+ *
+ * The caller loads the client from authoritative storage. This function then
+ * refuses to expose a redirect target until that client is active and the URI
+ * is an exact, secure registration match. Routes can therefore return local
+ * errors for forged client or redirect input without creating an open redirect.
+ */
+export declare function validateOAuthAuthorizationRequest(provider: ResolvedOAuthProviderConfig, client: OAuthAuthorizationClientRegistration, input: OAuthAuthorizationRequestInput): ValidatedOAuthAuthorizationRequest;
+export declare interface OAuthAuthorizationClientRegistration {
+  id: string | number
+  type: 'confidential' | 'public'
+  revoked: boolean
+  redirectUris: readonly string[]
+  grantTypes: readonly string[]
+  scopes: readonly string[]
+  resources: readonly string[]
+}
+export declare interface OAuthAuthorizationRequestInput {
+  responseType: string
+  clientId: string
+  redirectUri: string
+  scope?: string
+  resource?: string | readonly string[]
+  state?: string
+  codeChallenge?: string
+  codeChallengeMethod?: string
+}
+export declare interface ValidatedOAuthAuthorizationRequest {
+  responseType: 'code'
+  clientId: string
+  clientType: 'confidential' | 'public'
+  redirectUri: string
+  scopes: string[]
+  resources: string[]
+  audiences: string[]
+  state: string | null
+  codeChallenge: string
+  codeChallengeMethod: 'S256'
+}
+export type OAuthAuthorizationRequestErrorCode = | 'invalid_request'
+    | 'unauthorized_client'
+    | 'unsupported_response_type'
+    | 'invalid_scope'
+    | 'invalid_target';
+/** A protocol failure plus the only callback target that is safe to use. */
+export declare class OAuthAuthorizationRequestError extends Error {
+  public readonly code: OAuthAuthorizationRequestErrorCode;
+  public readonly redirectUri?: string | null;
+  public readonly state?: string | null;
+  constructor(code: OAuthAuthorizationRequestErrorCode, message: string, redirectUri?: string | null, state?: string | null);
+}

package/dist/oauth-authorization.js

@@ -0,0 +1 @@
+import{isValidS256CodeChallenge}from"./oauth-pkce";export class OAuthAuthorizationRequestError extends Error{code;redirectUri;state;constructor(code,message,redirectUri=null,state=null){super(message);this.code=code;this.redirectUri=redirectUri;this.state=state;this.name="OAuthAuthorizationRequestError"}}function reject(code,message,redirectUri=null,state=null){throw new OAuthAuthorizationRequestError(code,message,redirectUri,state)}export function isValidOAuthRedirectUri(value){if(value.includes("*"))return!1;let url;try{url=new URL(value)}catch{return!1}if(url.username||url.password||url.hash)return!1;const loopback=url.hostname==="localhost"||url.hostname==="127.0.0.1"||url.hostname==="[::1]";return url.protocol==="https:"||url.protocol==="http:"&&loopback}function requestedScopes(value,redirectUri,state){if(value==null||value==="")return[];const scopes=value.split(" ");if(scopes.some((scope)=>!scope||!/^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)))reject("invalid_scope","OAuth scopes must be space-separated visible ASCII tokens.",redirectUri,state);return[...new Set(scopes)]}function requestedAudiences(value,redirectUri,state){if(value==null)return[];const resources=typeof value==="string"?[value]:[...value];if(resources.some((resource)=>!resource))reject("invalid_target","OAuth resources must not be empty.",redirectUri,state);return[...new Set(resources)]}export function validateOAuthAuthorizationRequest(provider,client,input){if(String(client.id)!==input.clientId)reject("invalid_request","OAuth client identifier does not match the loaded client.");if(client.revoked)reject("unauthorized_client","OAuth client is disabled.");if(!provider.clientTypes.includes(client.type))reject("unauthorized_client","OAuth client type is not enabled by this provider.");if(!client.redirectUris.includes(input.redirectUri)||!isValidOAuthRedirectUri(input.redirectUri))reject("invalid_request","OAuth redirect URI is not an exact secure registration match.");const state=typeof input.state==="string"?input.state:null,redirectUri=input.redirectUri;if(input.responseType!=="code")reject("unsupported_response_type","Only response_type=code is supported.",redirectUri,state);if(!client.grantTypes.includes("authorization_code"))reject("unauthorized_client","OAuth client may not use the authorization code grant.",redirectUri,state);if(input.codeChallengeMethod!=="S256")reject("invalid_request","OAuth authorization requests require code_challenge_method=S256.",redirectUri,state);if(!isValidS256CodeChallenge(input.codeChallenge))reject("invalid_request","OAuth authorization request has an invalid S256 code challenge.",redirectUri,state);const scopes=requestedScopes(input.scope,redirectUri,state);for(const scope of scopes)if(!provider.scopes[scope]||!client.scopes.includes(scope))reject("invalid_scope",`OAuth scope is not registered for this client: ${scope}`,redirectUri,state);const audiences=requestedAudiences(input.resource,redirectUri,state),resources=[];for(const audience of audiences){const matchingResources=Object.entries(provider.resources).filter(([,resource])=>resource.audience===audience).map(([key])=>key);if(matchingResources.length!==1||!client.resources.includes(matchingResources[0]))reject("invalid_target",`OAuth resource is not registered for this client: ${audience}`,redirectUri,state);resources.push(matchingResources[0])}for(const scope of scopes){const allowedResources=provider.scopes[scope]?.resources;if(!allowedResources?.length)continue;if(!resources.length||resources.some((resource)=>!allowedResources.includes(resource)))reject("invalid_target",`OAuth scope is not valid for the requested resource: ${scope}`,redirectUri,state)}return{responseType:"code",clientId:input.clientId,clientType:client.type,redirectUri,scopes,resources,audiences,state,codeChallenge:input.codeChallenge,codeChallengeMethod:"S256"}}

package/dist/oauth-client-registration.d.ts

@@ -0,0 +1,78 @@
+import { sqlHelpers } from '@stacksjs/database/runtime';
+import type { OAuthAuthorizationClientRegistration } from './oauth-authorization';
+import type { ResolvedOAuthProviderConfig } from './oauth-provider';
+/** Validate client-controlled metadata before any secret or database row exists. */
+export declare function validateOAuthClientRegistration(provider: ResolvedOAuthProviderConfig, input: OAuthClientRegistrationInput): ValidatedOAuthClientRegistration;
+/** Load only complete provider registration metadata from authoritative storage. */
+export declare function loadOAuthAuthorizationClient(clientId: string): Promise<OAuthAuthorizationClientRegistration | null>;
+/** List complete provider clients owned by one account without exposing secret hashes. */
+export declare function listOAuthClients(ownerId: number): Promise<ManagedOAuthClient[]>;
+/** Edit one active owner-managed client without changing its authentication class. */
+export declare function updateOAuthClient(provider: ResolvedOAuthProviderConfig, ownerId: number, clientId: number, input: OAuthClientUpdateInput): Promise<ManagedOAuthClient | null>;
+/** Authenticate one provider client and hold its policy stable through completion. */
+export declare function withAuthenticatedOAuthTokenClient<T>(clientId: string, clientSecret: string | undefined, complete: (client: OAuthAuthorizationClientRegistration) => Promise<T>): Promise<T | null>;
+/** Validate and persist one owner-managed provider client. */
+export declare function registerOAuthClient(provider: ResolvedOAuthProviderConfig, ownerId: number, input: OAuthClientRegistrationInput): Promise<RegisteredOAuthClientResult>;
+/** Rotate one active confidential client's secret and reveal the replacement once. */
+export declare function rotateOAuthClientSecret(ownerId: number, clientId: number): Promise<string | null>;
+/** Disable one owner-managed client and revoke every credential it issued. */
+export declare function disableOAuthClient(ownerId: number, clientId: number): Promise<boolean>;
+export declare interface OAuthClientRegistrationInput {
+  name: string
+  type: 'confidential' | 'public'
+  tokenEndpointAuthMethod: OAuthTokenEndpointAuthMethod
+  redirectUris: readonly string[]
+  grantTypes: readonly string[]
+  scopes: readonly string[]
+  resources: readonly string[]
+}
+export declare interface OAuthClientUpdateInput {
+  name: string
+  redirectUris: readonly string[]
+  grantTypes: readonly string[]
+  scopes: readonly string[]
+  resources: readonly string[]
+}
+export declare interface ValidatedOAuthClientRegistration extends OAuthClientRegistrationInput {
+  name: string
+  redirectUris: string[]
+  grantTypes: string[]
+  scopes: string[]
+  resources: string[]
+  requiresSecret: boolean
+}
+export declare interface RegisteredOAuthClient {
+  id: number
+  ownerId: number
+  name: string
+  type: 'confidential' | 'public'
+  tokenEndpointAuthMethod: OAuthTokenEndpointAuthMethod
+  redirectUris: string[]
+  grantTypes: string[]
+  scopes: string[]
+  resources: string[]
+  revoked: false
+  createdAt: Date
+}
+export declare interface RegisteredOAuthClientResult {
+  client: RegisteredOAuthClient
+  plainTextSecret?: string
+}
+export declare interface ManagedOAuthClient {
+  id: number
+  ownerId: number
+  name: string
+  type: 'confidential' | 'public'
+  tokenEndpointAuthMethod: OAuthTokenEndpointAuthMethod
+  redirectUris: readonly string[]
+  grantTypes: readonly string[]
+  scopes: readonly string[]
+  resources: readonly string[]
+  revoked: boolean
+  createdAt: Date
+}
+export type OAuthTokenEndpointAuthMethod = 'client_secret_basic' | 'none';
+declare type OAuthSqlHelpers = ReturnType<typeof sqlHelpers>;
+export declare class OAuthClientRegistrationError extends Error {
+  constructor(message: string);
+}

package/dist/oauth-client-registration.js

@@ -0,0 +1,78 @@
+import{randomBytes}from"node:crypto";import{db,getDatabaseDialect,markContextWrote,mutationCount,parseSqlDateTime,sqlDateTime,sqlHelpers}from"@stacksjs/database/runtime";import{makeHash,verifyHash}from"@stacksjs/security";import{isValidOAuthRedirectUri}from"./oauth-authorization";export class OAuthClientRegistrationError extends Error{constructor(message){super(message);this.name="OAuthClientRegistrationError"}}function reject(message){throw new OAuthClientRegistrationError(message)}function explicitUnique(name,values,options={}){if(options.required&&values.length===0)reject(`OAuth client must register at least one ${name}.`);if(values.some((value)=>!value))reject(`OAuth client ${name} entries must not be empty.`);if(new Set(values).size!==values.length)reject(`OAuth client ${name} contains a duplicate entry.`);return[...values]}export function validateOAuthClientRegistration(provider,input){const name=input.name.trim();if(!name||name.length>100||/[\u0000-\u001F\u007F]/.test(name))reject("OAuth client name must be 1 to 100 characters without control characters.");if(!provider.clientTypes.includes(input.type))reject(`OAuth client type is not enabled by this provider: ${input.type}`);if(input.type==="public"&&input.tokenEndpointAuthMethod!=="none")reject("Public OAuth clients must use token endpoint authentication method none.");if(input.type==="confidential"&&input.tokenEndpointAuthMethod!=="client_secret_basic")reject("Confidential OAuth clients must use token endpoint authentication method client_secret_basic.");const redirectUris=explicitUnique("redirect URI",input.redirectUris,{required:!0});if(redirectUris.some((uri)=>!isValidOAuthRedirectUri(uri)))reject("OAuth client redirect URIs must be exact HTTPS URLs or exact loopback HTTP URLs, without credentials, fragments, or wildcards.");const grantTypes=explicitUnique("grant type",input.grantTypes,{required:!0});if(!grantTypes.includes("authorization_code"))reject("OAuth client grant types must include authorization_code.");for(const grantType of grantTypes)if(!provider.grantTypes.includes(grantType))reject(`OAuth client requested an unsupported grant type: ${grantType}`);const scopes=explicitUnique("scope",input.scopes,{required:!0});for(const scope of scopes)if(!provider.scopes[scope])reject(`OAuth client requested an unregistered scope: ${scope}`);const resources=explicitUnique("resource",input.resources);for(const resource of resources)if(!provider.resources[resource])reject(`OAuth client requested an unregistered resource: ${resource}`);for(const scope of scopes){const allowedResources=provider.scopes[scope]?.resources;if(allowedResources?.length&&!resources.some((resource)=>allowedResources.includes(resource)))reject(`OAuth client scope requires a registered resource: ${scope}`)}return{name,type:input.type,tokenEndpointAuthMethod:input.tokenEndpointAuthMethod,redirectUris,grantTypes,scopes,resources,requiresSecret:input.type==="confidential"}}function storedValues(value){if(value==null)return null;try{const parsed=JSON.parse(value);return Array.isArray(parsed)&&parsed.every((item)=>typeof item==="string")?parsed:null}catch{return null}}function inactive(value){return value===!1||value===0}function sameValues(left,right){return left.length===right.length&&left.every((value,index)=>value===right[index])}async function revokeOAuthClientAuthorizationState(trx,sql,clientId,now){const revoked=sql.isPostgres?!0:1;await trx.unsafe(`
+    UPDATE oauth_grants
+    SET revoked_at = ${sql.param(1)}, updated_at = ${sql.param(2)}
+    WHERE client_id = ${sql.param(3)} AND revoked_at IS NULL
+  `,[now,now,clientId]);await trx.unsafe(`
+    UPDATE oauth_auth_codes
+    SET consumed_at = ${sql.param(1)}
+    WHERE client_id = ${sql.param(2)} AND consumed_at IS NULL
+  `,[now,clientId]);await trx.unsafe(`
+    UPDATE oauth_authorization_requests
+    SET consumed_at = ${sql.param(1)}
+    WHERE client_id = ${sql.param(2)} AND consumed_at IS NULL
+  `,[now,clientId]);await trx.unsafe(`
+    UPDATE oauth_refresh_tokens
+    SET revoked = ${sql.param(1)}
+    WHERE access_token_id IN (
+      SELECT id FROM oauth_access_tokens WHERE oauth_client_id = ${sql.param(2)}
+    )
+  `,[revoked,clientId]);await trx.unsafe(`
+    UPDATE oauth_access_tokens
+    SET revoked = ${sql.param(1)}, updated_at = ${sql.param(2)}
+    WHERE oauth_client_id = ${sql.param(3)}
+  `,[revoked,now,clientId])}function storedFlag(value){if(value===!1||value===0)return!1;if(value===!0||value===1)return!0;return null}function authorizationClientFromStored(row,id){const redirectUris=storedValues(row?.redirect_uris??null),grantTypes=storedValues(row?.grant_types??null),scopes=storedValues(row?.allowed_scopes??null),resources=storedValues(row?.allowed_resources??null),revoked=row?storedFlag(row.revoked):null,type=row?.client_type,method=row?.token_endpoint_auth_method;if(!row||String(row.id)!==String(id)||type!=="public"&&type!=="confidential"||method!=="none"&&method!=="client_secret_basic"||(type==="public"?method!=="none"||row.secret!=null:method!=="client_secret_basic"||!row.secret)||!redirectUris?.length||!grantTypes?.includes("authorization_code")||!scopes?.length||!resources||new Set(redirectUris).size!==redirectUris.length||new Set(grantTypes).size!==grantTypes.length||new Set(scopes).size!==scopes.length||new Set(resources).size!==resources.length||redirectUris.some((uri)=>!isValidOAuthRedirectUri(uri))||row.redirect!==redirectUris[0]||!inactive(row.personal_access_client)||!inactive(row.password_client)||revoked==null)return null;return{id,type,revoked,redirectUris,grantTypes,scopes,resources}}async function storedAuthorizationClient(clientId){const id=Number(clientId);if(!Number.isSafeInteger(id)||id<=0)return null;const sql=sqlHelpers(getDatabaseDialect()),row=(await db.primary.unsafe(`
+    SELECT id, secret, redirect, client_type, redirect_uris, grant_types,
+      token_endpoint_auth_method, allowed_scopes, allowed_resources,
+      personal_access_client, password_client, revoked
+    FROM oauth_clients WHERE id = ${sql.param(1)} LIMIT 1
+  `,[id]))[0],client=authorizationClientFromStored(row,id);return row&&client?{client,row}:null}export async function loadOAuthAuthorizationClient(clientId){return(await storedAuthorizationClient(clientId))?.client??null}export async function listOAuthClients(ownerId){if(!Number.isSafeInteger(ownerId)||ownerId<=0)return[];const sql=sqlHelpers(getDatabaseDialect());return(await db.primary.unsafe(`
+    SELECT id, user_id, name, secret, redirect, client_type, redirect_uris, grant_types,
+      token_endpoint_auth_method, allowed_scopes, allowed_resources, personal_access_client,
+      password_client, revoked, created_at
+    FROM oauth_clients
+    WHERE user_id = ${sql.param(1)}
+    ORDER BY created_at DESC, id DESC
+  `,[ownerId])).flatMap((row)=>{const id=Number(row.id),storedOwnerId=Number(row.user_id),client=authorizationClientFromStored(row,id),createdAt=parseSqlDateTime(row.created_at);if(!client||!Number.isSafeInteger(storedOwnerId)||storedOwnerId!==ownerId||!createdAt)return[];return[{id,ownerId,name:row.name,type:client.type,tokenEndpointAuthMethod:row.token_endpoint_auth_method,redirectUris:client.redirectUris,grantTypes:client.grantTypes,scopes:client.scopes,resources:client.resources,revoked:client.revoked,createdAt}]})}export async function updateOAuthClient(provider,ownerId,clientId,input){if(!Number.isSafeInteger(ownerId)||ownerId<=0||!Number.isSafeInteger(clientId)||clientId<=0)return null;const sql=sqlHelpers(getDatabaseDialect()),lock=sql.isSqlite?"":" FOR UPDATE",result=await db.transaction(async(rawTrx)=>{const trx=rawTrx,row=(await trx.unsafe(`
+      SELECT id, user_id, name, secret, redirect, client_type, redirect_uris, grant_types,
+        token_endpoint_auth_method, allowed_scopes, allowed_resources, personal_access_client,
+        password_client, revoked, created_at
+      FROM oauth_clients
+      WHERE id = ${sql.param(1)} AND user_id = ${sql.param(2)}
+      LIMIT 1${lock}
+    `,[clientId,ownerId]))[0],current=authorizationClientFromStored(row,clientId),createdAt=row?parseSqlDateTime(row.created_at):null;if(!row||!current||current.revoked||!createdAt)return null;const validated=validateOAuthClientRegistration(provider,{...input,type:current.type,tokenEndpointAuthMethod:row.token_endpoint_auth_method}),policyChanged=!sameValues(current.redirectUris,validated.redirectUris)||!sameValues(current.grantTypes,validated.grantTypes)||!sameValues(current.scopes,validated.scopes)||!sameValues(current.resources,validated.resources),changed=policyChanged||row.name!==validated.name,client={id:clientId,ownerId,name:validated.name,type:current.type,tokenEndpointAuthMethod:validated.tokenEndpointAuthMethod,redirectUris:validated.redirectUris,grantTypes:validated.grantTypes,scopes:validated.scopes,resources:validated.resources,revoked:!1,createdAt};if(!changed)return{changed:!1,client};const active=sql.isPostgres?!1:0,now=sqlDateTime(new Date),updated=await trx.unsafe(`
+      UPDATE oauth_clients
+      SET name = ${sql.param(1)}, redirect = ${sql.param(2)}, redirect_uris = ${sql.param(3)},
+        grant_types = ${sql.param(4)}, allowed_scopes = ${sql.param(5)}, allowed_resources = ${sql.param(6)},
+        updated_at = ${sql.param(7)}
+      WHERE id = ${sql.param(8)} AND user_id = ${sql.param(9)} AND revoked = ${sql.param(10)}
+    `,[validated.name,validated.redirectUris[0],JSON.stringify(validated.redirectUris),JSON.stringify(validated.grantTypes),JSON.stringify(validated.scopes),JSON.stringify(validated.resources),now,clientId,ownerId,active]);if(mutationCount(updated)!==1)return null;if(policyChanged)await revokeOAuthClientAuthorizationState(trx,sql,clientId,now);return{changed:!0,client}});if(!result)return null;if(result.changed)markContextWrote();return result.client}export async function withAuthenticatedOAuthTokenClient(clientId,clientSecret,complete){const id=Number(clientId);if(!Number.isSafeInteger(id)||id<=0||clientSecret!=null&&clientSecret.length>4096)return null;const sql=sqlHelpers(getDatabaseDialect()),lock=sql.isPostgres?" FOR SHARE":sql.isMysql?" LOCK IN SHARE MODE":"";return db.transaction(async(rawTrx)=>{const row=(await rawTrx.unsafe(`
+      SELECT id, secret, redirect, client_type, redirect_uris, grant_types,
+        token_endpoint_auth_method, allowed_scopes, allowed_resources,
+        personal_access_client, password_client, revoked
+      FROM oauth_clients WHERE id = ${sql.param(1)} LIMIT 1${lock}
+    `,[id]))[0],client=authorizationClientFromStored(row,id);if(!row||!client||client.revoked)return null;if(client.type==="public")return clientSecret===void 0?complete(client):null;if(!clientSecret||!row.secret)return null;let verified=!1;try{verified=await verifyHash(clientSecret,row.secret)}catch{return null}return verified?complete(client):null})}export async function registerOAuthClient(provider,ownerId,input){if(!Number.isSafeInteger(ownerId)||ownerId<=0)throw TypeError("OAuth client owner identifier must be a positive safe integer.");const client=validateOAuthClientRegistration(provider,input),plainTextSecret=client.requiresSecret?randomBytes(40).toString("hex"):void 0,storedSecret=plainTextSecret?await makeHash(plainTextSecret,{algorithm:"bcrypt"}):null,sql=sqlHelpers(getDatabaseDialect()),createdAt=new Date;if(sql.isMysql)createdAt.setUTCMilliseconds(0);const disabled=sql.isPostgres?!1:0,stored=await db.transaction(async(rawTrx)=>{const trx=rawTrx,values=sql.params(ownerId,client.name,storedSecret,"local",client.redirectUris[0],client.type,JSON.stringify(client.redirectUris),JSON.stringify(client.grantTypes),client.tokenEndpointAuthMethod,JSON.stringify(client.scopes),JSON.stringify(client.resources),disabled,disabled,disabled,sqlDateTime(createdAt)),returning=sql.isMysql?"":" RETURNING id",inserted=await trx.unsafe(`
+      INSERT INTO oauth_clients (
+        user_id, name, secret, provider, redirect, client_type, redirect_uris, grant_types,
+        token_endpoint_auth_method, allowed_scopes, allowed_resources, personal_access_client,
+        password_client, revoked, created_at
+      ) VALUES (${values.sql})${returning}
+    `,values.values),idRows=sql.isMysql?await trx.unsafe("SELECT LAST_INSERT_ID() AS id"):inserted,id=Number(idRows[0]?.id);if(!Number.isSafeInteger(id)||id<=0)throw Error("Failed to resolve the registered OAuth client identifier.");const row=(await trx.unsafe(`SELECT * FROM oauth_clients WHERE id = ${sql.param(1)} LIMIT 1`,[id]))[0];if(!row||String(row.user_id)!==String(ownerId)||row.name!==client.name||row.secret!==storedSecret||row.redirect!==client.redirectUris[0]||row.client_type!==client.type||JSON.stringify(storedValues(row.redirect_uris))!==JSON.stringify(client.redirectUris)||JSON.stringify(storedValues(row.grant_types))!==JSON.stringify(client.grantTypes)||row.token_endpoint_auth_method!==client.tokenEndpointAuthMethod||JSON.stringify(storedValues(row.allowed_scopes))!==JSON.stringify(client.scopes)||JSON.stringify(storedValues(row.allowed_resources))!==JSON.stringify(client.resources)||!inactive(row.personal_access_client)||!inactive(row.password_client)||!inactive(row.revoked))throw Error("Failed to persist the registered OAuth client policy.");return{id,createdAt:parseSqlDateTime(row.created_at)??createdAt}});markContextWrote();return{client:{id:stored.id,ownerId,name:client.name,type:client.type,tokenEndpointAuthMethod:client.tokenEndpointAuthMethod,redirectUris:client.redirectUris,grantTypes:client.grantTypes,scopes:client.scopes,resources:client.resources,revoked:!1,createdAt:stored.createdAt},...plainTextSecret===void 0?{}:{plainTextSecret}}}export async function rotateOAuthClientSecret(ownerId,clientId){if(!Number.isSafeInteger(ownerId)||ownerId<=0||!Number.isSafeInteger(clientId)||clientId<=0)return null;const plainTextSecret=randomBytes(40).toString("hex"),storedSecret=await makeHash(plainTextSecret,{algorithm:"bcrypt"}),sql=sqlHelpers(getDatabaseDialect()),lock=sql.isSqlite?"":" FOR UPDATE";if(!await db.transaction(async(rawTrx)=>{const trx=rawTrx,client=(await trx.unsafe(`
+      SELECT client_type, token_endpoint_auth_method, revoked
+      FROM oauth_clients
+      WHERE id = ${sql.param(1)} AND user_id = ${sql.param(2)}
+      LIMIT 1${lock}
+    `,[clientId,ownerId]))[0];if(!client||client.client_type!=="confidential"||client.token_endpoint_auth_method!=="client_secret_basic"||!inactive(client.revoked))return!1;const active=sql.isPostgres?!1:0,changed=await trx.unsafe(`
+      UPDATE oauth_clients
+      SET secret = ${sql.param(1)}, updated_at = ${sql.param(2)}
+      WHERE id = ${sql.param(3)} AND user_id = ${sql.param(4)}
+        AND client_type = ${sql.param(5)} AND token_endpoint_auth_method = ${sql.param(6)}
+        AND revoked = ${sql.param(7)}
+    `,[storedSecret,sqlDateTime(new Date),clientId,ownerId,"confidential","client_secret_basic",active]);return mutationCount(changed)===1}))return null;markContextWrote();return plainTextSecret}export async function disableOAuthClient(ownerId,clientId){if(!Number.isSafeInteger(ownerId)||ownerId<=0||!Number.isSafeInteger(clientId)||clientId<=0)return!1;const sql=sqlHelpers(getDatabaseDialect()),lock=sql.isSqlite?"":" FOR UPDATE",disabled=await db.transaction(async(rawTrx)=>{const trx=rawTrx,rows=await trx.unsafe(`
+      SELECT id, revoked FROM oauth_clients
+      WHERE id = ${sql.param(1)} AND user_id = ${sql.param(2)}
+      LIMIT 1${lock}
+    `,[clientId,ownerId]);if(!rows[0]||!inactive(rows[0].revoked))return!1;const now=sqlDateTime(new Date),revoked=sql.isPostgres?!0:1,active=sql.isPostgres?!1:0,changed=await trx.unsafe(`
+      UPDATE oauth_clients
+      SET revoked = ${sql.param(1)}, updated_at = ${sql.param(2)}
+      WHERE id = ${sql.param(3)} AND user_id = ${sql.param(4)} AND revoked = ${sql.param(5)}
+    `,[revoked,now,clientId,ownerId,active]);if(mutationCount(changed)!==1)return!1;await revokeOAuthClientAuthorizationState(trx,sql,clientId,now);return!0});if(disabled)markContextWrote();return disabled}

package/dist/oauth-consent.d.ts

@@ -0,0 +1,34 @@
+import type { OAuthAuthorizationRequestSessionResult } from './oauth-authorization-requests';
+import type { ValidatedOAuthAuthorizationRequest } from './oauth-authorization';
+/** Whether a recent active grant already covers the requested consent. */
+export declare function hasReusableOAuthConsent(input: ReusableOAuthConsentInput): Promise<boolean>;
+/** Atomically turn one authenticated browser approval into a grant and code. */
+export declare function approveOAuthAuthorizationRequestSession(input: ApproveOAuthAuthorizationRequestSessionInput): Promise<OAuthAuthorizationRequestSessionResult<OAuthAuthorizationConsentResult>>;
+/** Consume one browser-bound denial without creating a grant or authorization code. */
+export declare function denyOAuthAuthorizationRequestSession(requestId: string, browserSessionId: string): Promise<OAuthAuthorizationRequestSessionResult<OAuthAuthorizationDenialResult>>;
+export declare interface ApproveOAuthAuthorizationRequestSessionInput {
+  requestId: string
+  browserSessionId: string
+  subjectType: string
+  subjectId: number
+  workspaceId?: string | null
+  authorizationCodeLifetimeMs: number
+}
+export declare interface OAuthAuthorizationConsentResult {
+  code: string
+  grantId: string
+  redirectUri: string
+  state: string | null
+}
+export declare interface OAuthAuthorizationDenialResult {
+  error: 'access_denied'
+  redirectUri: string
+  state: string | null
+}
+export declare interface ReusableOAuthConsentInput {
+  request: ValidatedOAuthAuthorizationRequest
+  subjectType: string
+  subjectId: number
+  workspaceId?: string | null
+  rememberForMs: number
+}

package/dist/oauth-consent.js

@@ -0,0 +1,12 @@
+import{db,getDatabaseDialect,parseSqlDateTime,sqlDateTime,sqlHelpers}from"@stacksjs/database/runtime";import{issueAuthorizationCode}from"./oauth-authorization-codes";import{withOAuthAuthorizationRequestSession}from"./oauth-authorization-requests";import{loadOAuthAuthorizationClient}from"./oauth-client-registration";import{createOAuthGrant}from"./oauth-grants";function storedValues(value){try{const parsed=JSON.parse(value);return Array.isArray(parsed)&&parsed.every((item)=>typeof item==="string"&&item.length>0)&&new Set(parsed).size===parsed.length?parsed:null}catch{return null}}function includesAll(approved,requested){return requested.every((value)=>approved.includes(value))}function includesResourceBindings(approvedResources,approvedAudiences,requestedResources,requestedAudiences){if(approvedResources.length!==approvedAudiences.length||requestedResources.length!==requestedAudiences.length)return!1;return requestedResources.every((resource,index)=>{const approvedIndex=approvedResources.indexOf(resource);return approvedIndex>=0&&approvedAudiences[approvedIndex]===requestedAudiences[index]})}export async function hasReusableOAuthConsent(input){if(!Number.isFinite(input.rememberForMs)||input.rememberForMs<=0||!Number.isSafeInteger(input.subjectId)||input.subjectId<=0||!/^[A-Za-z0-9_.:-]{1,255}$/.test(input.subjectType)||input.workspaceId!=null&&(!input.workspaceId||input.workspaceId.length>255))return!1;const clientId=Number(input.request.clientId),cutoff=new Date(Date.now()-input.rememberForMs);if(!Number.isSafeInteger(clientId)||clientId<=0||!Number.isFinite(cutoff.getTime()))return!1;const client=await loadOAuthAuthorizationClient(input.request.clientId);if(!client||client.revoked||client.type!==input.request.clientType||!client.redirectUris.includes(input.request.redirectUri)||!client.grantTypes.includes("authorization_code")||!includesAll(client.scopes,input.request.scopes)||!includesAll(client.resources,input.request.resources))return!1;const sql=sqlHelpers(getDatabaseDialect()),params=[clientId,input.subjectType,input.subjectId,sqlDateTime(cutoff)],workspace=input.workspaceId??null,workspacePredicate=workspace===null?"g.workspace_id IS NULL":`g.workspace_id = ${sql.param(params.push(workspace))}`;return(await db.primary.unsafe(`
+    SELECT g.scopes, g.resources, g.audiences, g.created_at
+    FROM oauth_grants g
+    JOIN oauth_clients c ON c.id = g.client_id AND c.revoked = ${sql.boolFalse}
+    WHERE g.client_id = ${sql.param(1)}
+      AND g.subject_type = ${sql.param(2)}
+      AND g.subject_id = ${sql.param(3)}
+      AND g.revoked_at IS NULL
+      AND g.created_at >= ${sql.param(4)}
+      AND ${workspacePredicate}
+    ORDER BY g.created_at DESC, g.id DESC
+  `,params)).some((row)=>{const scopes=storedValues(row.scopes),resources=storedValues(row.resources),audiences=storedValues(row.audiences);return(parseSqlDateTime(row.created_at)?.getTime()??0)>=cutoff.getTime()&&scopes!==null&&resources!==null&&audiences!==null&&includesAll(scopes,input.request.scopes)&&includesResourceBindings(resources,audiences,input.request.resources,input.request.audiences)})}export async function approveOAuthAuthorizationRequestSession(input){if(!Number.isSafeInteger(input.authorizationCodeLifetimeMs)||input.authorizationCodeLifetimeMs<=0)throw TypeError("OAuth authorization code lifetime must be a positive safe integer.");return withOAuthAuthorizationRequestSession(input.requestId,input.browserSessionId,async(request)=>{const grant=await createOAuthGrant({clientId:Number(request.clientId),subjectType:input.subjectType,subjectId:input.subjectId,scopes:request.scopes,resources:request.resources,audiences:request.audiences,workspaceId:input.workspaceId});return{code:await issueAuthorizationCode({grantId:grant.id,redirectUri:request.redirectUri,codeChallenge:request.codeChallenge,lifetimeMs:input.authorizationCodeLifetimeMs}),grantId:grant.id,redirectUri:request.redirectUri,state:request.state}})}export async function denyOAuthAuthorizationRequestSession(requestId,browserSessionId){return withOAuthAuthorizationRequestSession(requestId,browserSessionId,async(request)=>({error:"access_denied",redirectUri:request.redirectUri,state:request.state}))}

package/dist/oauth-delegated-access.d.ts

@@ -0,0 +1,23 @@
+import type { AccessToken } from '@stacksjs/types';
+/** Resolve and authorize a delegated bearer without promoting it to a user session. */
+export declare function authorizeOAuthDelegatedToken(bearer: string, requirement: OAuthDelegatedAccessRequirement): Promise<OAuthDelegatedAccessResult>;
+/** Format an RFC 6750 challenge for a rejected delegated bearer. */
+export declare function oauthBearerAuthorizationErrorResponse(failure: OAuthDelegatedAccessFailure): Response;
+export declare interface OAuthDelegatedSubject {
+  type: string
+  id: number
+  clientId: number
+  grantId: string
+  workspaceId: string | null
+}
+export declare interface OAuthDelegatedAccessRequirement {
+  scopes: readonly string[]
+  resource: string
+  audience: string
+  workspaceId: string | null
+  isSubjectEligible: (subject: OAuthDelegatedSubject) => boolean | Promise<boolean>
+}
+export type OAuthDelegatedAccessResult = { ok: true, token: AccessToken }
+    | { ok: false, reason: 'invalid_token' }
+    | { ok: false, reason: 'insufficient_scope', requiredScopes: string[] }
+declare type OAuthDelegatedAccessFailure = Exclude<OAuthDelegatedAccessResult, { ok: true }>;

package/dist/oauth-delegated-access.js

@@ -0,0 +1 @@
+import{findToken}from"./tokens";const POLICY_TOKEN=/^[\x21\x23-\x5B\x5D-\x7E]+$/;function validateRequirement(requirement){if(!requirement.scopes.length||requirement.scopes.some((scope)=>!POLICY_TOKEN.test(scope))||new Set(requirement.scopes).size!==requirement.scopes.length)throw TypeError("OAuth delegated access requires unique non-empty scope tokens.");if(!POLICY_TOKEN.test(requirement.resource))throw TypeError("OAuth delegated access resource is invalid.");try{const audience=new URL(requirement.audience);if(audience.username||audience.password||audience.hash)throw TypeError("invalid audience")}catch{throw TypeError("OAuth delegated access audience must be an absolute URI without credentials or a fragment.")}if(requirement.workspaceId!=null&&(!requirement.workspaceId||requirement.workspaceId.length>255))throw TypeError("OAuth delegated access workspace identifier must be 1 to 255 characters.")}export async function authorizeOAuthDelegatedToken(bearer,requirement){validateRequirement(requirement);const token=await findToken(bearer),subjectType=token?.subjectType,subjectId=token?.subjectId,grantId=token?.grantId;if(!token||!subjectType||!Number.isSafeInteger(subjectId)||!grantId||!token.resources?.includes(requirement.resource)||!token.audiences?.includes(requirement.audience)||(token.workspaceId??null)!==requirement.workspaceId)return{ok:!1,reason:"invalid_token"};if(!await requirement.isSubjectEligible({type:subjectType,id:subjectId,clientId:token.clientId,grantId,workspaceId:token.workspaceId??null}))return{ok:!1,reason:"invalid_token"};if(!requirement.scopes.every((scope)=>token.scopes.includes(scope)))return{ok:!1,reason:"insufficient_scope",requiredScopes:[...requirement.scopes]};return{ok:!0,token}}export function oauthBearerAuthorizationErrorResponse(failure){const insufficient=failure.reason==="insufficient_scope",scope=insufficient?`, scope="${failure.requiredScopes.join(" ")}"`:"";return new Response(JSON.stringify({error:failure.reason}),{status:insufficient?403:401,headers:{"Cache-Control":"no-store","Content-Type":"application/json; charset=utf-8","WWW-Authenticate":`Bearer error="${failure.reason}"${scope}`}})}