feat(auth): add JWKS model and integrate JWT plugin for key management

Author: hotlong

packages/platform-objects/src/identity/index.ts

@@ -30,3 +30,4 @@ export { SysOauthApplication } from './sys-oauth-application.object.js';
 export { SysOauthAccessToken } from './sys-oauth-access-token.object.js';
 export { SysOauthRefreshToken } from './sys-oauth-refresh-token.object.js';
 export { SysOauthConsent } from './sys-oauth-consent.object.js';
+export { SysJwks } from './sys-jwks.object.js';

packages/platform-objects/src/identity/sys-jwks.object.ts

@@ -0,0 +1,68 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_jwks — JWKS (JSON Web Key Set) key pair store
+ *
+ * Backed by better-auth's `jwt` plugin. Each row is a single asymmetric
+ * key pair used to sign and verify JWTs (id_tokens, JWT access tokens)
+ * issued by this ObjectStack server when it acts as an OAuth/OIDC IdP.
+ *
+ * The plugin rotates keys automatically — older rows are kept until
+ * `expires_at` so existing tokens can still be verified.
+ *
+ * @namespace sys
+ */
+export const SysJwks = ObjectSchema.create({
+  name: 'sys_jwks',
+  label: 'JWKS Key',
+  pluralLabel: 'JWKS Keys',
+  icon: 'key',
+  isSystem: true,
+  description: 'Asymmetric key pairs used to sign and verify issued JWTs',
+  compactLayout: ['id', 'created_at', 'expires_at'],
+
+  fields: {
+    id: Field.text({
+      label: 'Key ID',
+      required: true,
+      readonly: true,
+      description: 'JWK `kid` value',
+    }),
+
+    public_key: Field.textarea({
+      label: 'Public Key',
+      required: true,
+      description: 'JSON-serialized JWK public key',
+    }),
+
+    private_key: Field.textarea({
+      label: 'Private Key',
+      required: true,
+      description: 'JSON-serialized JWK private key (encrypted at rest)',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+    }),
+
+    expires_at: Field.datetime({
+      label: 'Expires At',
+      required: false,
+      description: 'When the key may no longer be used to verify tokens',
+    }),
+  },
+
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: false,
+    apiMethods: [],
+    trash: false,
+    mru: false,
+  },
+});

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -21,6 +21,7 @@ import {
   buildTwoFactorPluginSchema,
   buildOauthProviderPluginSchema,
   buildDeviceAuthorizationPluginSchema,
+  buildJwtPluginSchema,
 } from './auth-schema-config.js';
 
 /**
@@ -303,6 +304,13 @@ export class AuthManager {
     // models — see `buildOauthProviderPluginSchema()` for the snake_case
     // mappings to ObjectStack's `sys_oauth_*` tables.
     if (pluginConfig?.oidcProvider) {
+      // The new @better-auth/oauth-provider package requires the `jwt`
+      // plugin (used to sign id_tokens / JWT access tokens). Register it
+      // automatically — it is otherwise an internal implementation detail
+      // and forcing every consumer to opt in would be poor DX.
+      const { jwt } = await import('better-auth/plugins');
+      plugins.push(jwt({ schema: buildJwtPluginSchema() }));
+
       const { oauthProvider } = await import('@better-auth/oauth-provider');
       const baseUrl = (this.config.baseUrl ?? '').replace(/\/$/, '');
       plugins.push(oauthProvider({

packages/plugins/plugin-auth/src/auth-plugin.ts

@@ -317,8 +317,44 @@ export class AuthPlugin implements Plugin {
       }
     });
 
+    // OIDC / OAuth 2.0 Authorization Server Metadata (RFC 8414) and
+    // OpenID Connect Discovery 1.0 require the well-known documents to be
+    // served from the **root** of the issuer URL — not under our auth
+    // basePath. `@better-auth/oauth-provider` ships dedicated helpers for
+    // this case (`oauthProviderAuthServerMetadata` /
+    // `oauthProviderOpenIdConfigMetadata`) which we mount here so external
+    // OIDC clients can discover the IdP at the canonical paths.
+    if (this.options.plugins?.oidcProvider) {
+      void this.registerOidcDiscoveryRoutes(rawApp, ctx).catch((error) => {
+        ctx.logger.error('Failed to register OIDC discovery routes', error as Error);
+      });
+    }
+
     ctx.logger.info(`Auth routes registered: All requests under ${basePath}/* forwarded to better-auth`);
   }
+
+  /**
+   * Mount the OIDC / OAuth 2.0 well-known discovery documents at the root
+   * URL. Required by RFC 8414 §3 and OpenID Connect Discovery 1.0 §4 — the
+   * documents must live at `/.well-known/{oauth-authorization-server,openid-configuration}`
+   * relative to the issuer, not under the auth basePath.
+   */
+  private async registerOidcDiscoveryRoutes(rawApp: any, ctx: PluginContext): Promise<void> {
+    const auth = await this.authManager!.getAuthInstance();
+    const { oauthProviderAuthServerMetadata, oauthProviderOpenIdConfigMetadata } = await import(
+      '@better-auth/oauth-provider'
+    );
+
+    const authServerHandler = oauthProviderAuthServerMetadata(auth as any);
+    const openidConfigHandler = oauthProviderOpenIdConfigMetadata(auth as any);
+
+    rawApp.get('/.well-known/oauth-authorization-server', (c: any) => authServerHandler(c.req.raw));
+    rawApp.get('/.well-known/openid-configuration', (c: any) => openidConfigHandler(c.req.raw));
+
+    ctx.logger.info(
+      'OIDC discovery endpoints mounted at /.well-known/{oauth-authorization-server,openid-configuration}',
+    );
+  }
 }
 
 

packages/plugins/plugin-auth/src/auth-schema-config.ts

@@ -532,6 +532,45 @@ export function buildOrganizationPluginSchema() {
   };
 }
 
+// ---------------------------------------------------------------------------
+// JWT plugin – jwks table
+// ---------------------------------------------------------------------------
+
+/**
+ * better-auth `jwt` plugin `jwks` model mapping.
+ *
+ * The JWT plugin maintains a small set of rotating asymmetric key pairs
+ * used to sign and verify issued JWTs (id_tokens for OIDC, JWT access
+ * tokens). It is required by the `@better-auth/oauth-provider` plugin.
+ *
+ * | camelCase (better-auth) | snake_case (ObjectStack) |
+ * |:------------------------|:-------------------------|
+ * | publicKey               | public_key               |
+ * | privateKey              | private_key              |
+ * | createdAt               | created_at               |
+ * | expiresAt               | expires_at               |
+ */
+export const AUTH_JWKS_SCHEMA = {
+  modelName: SystemObjectName.JWKS, // 'sys_jwks'
+  fields: {
+    publicKey: 'public_key',
+    privateKey: 'private_key',
+    createdAt: 'created_at',
+    expiresAt: 'expires_at',
+  },
+} as const;
+
+/**
+ * Builds the `schema` option for better-auth's `jwt()` plugin.
+ *
+ * @returns An object suitable for `jwt({ schema: … })`
+ */
+export function buildJwtPluginSchema() {
+  return {
+    jwks: AUTH_JWKS_SCHEMA,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Helper: build OAuth provider plugin schema option
 // ---------------------------------------------------------------------------

packages/plugins/plugin-auth/src/manifest.ts

@@ -14,6 +14,7 @@ import {
   SysDeviceCode,
   SysInvitation,
   SysMember,
+  SysJwks,
   SysOauthAccessToken,
   SysOauthApplication,
   SysOauthConsent,
@@ -49,6 +50,7 @@ export const authIdentityObjects: any[] = [
   SysOauthAccessToken,
   SysOauthRefreshToken,
   SysOauthConsent,
+  SysJwks,
   SysDeviceCode,
 ];
 

packages/spec/src/system/constants/system-names.test.ts

@@ -26,6 +26,8 @@ describe('SystemObjectName', () => {
     expect(SystemObjectName.OAUTH_ACCESS_TOKEN).toBe('sys_oauth_access_token');
     expect(SystemObjectName.OAUTH_REFRESH_TOKEN).toBe('sys_oauth_refresh_token');
     expect(SystemObjectName.OAUTH_CONSENT).toBe('sys_oauth_consent');
+    expect(SystemObjectName.DEVICE_CODE).toBe('sys_device_code');
+    expect(SystemObjectName.JWKS).toBe('sys_jwks');
     expect(SystemObjectName.USER_PREFERENCE).toBe('sys_user_preference');
     expect(SystemObjectName.ROLE).toBe('sys_role');
     expect(SystemObjectName.PERMISSION_SET).toBe('sys_permission_set');

packages/spec/src/system/constants/system-names.ts

@@ -52,6 +52,8 @@ export const SystemObjectName = {
   OAUTH_CONSENT: 'sys_oauth_consent',
   /** Authentication: pending device-authorization (RFC 8628) request */
   DEVICE_CODE: 'sys_device_code',
+  /** Authentication: JWKS key pair used to sign OIDC ID tokens / JWT access tokens */
+  JWKS: 'sys_jwks',
   /** Authentication: user preferences (theme, locale, etc.) */
   USER_PREFERENCE: 'sys_user_preference',
   /** Security: role definition for RBAC */