feat(backend): *WIP* Add machine authentication support

packages/agent-toolkit/src/lib/types.ts

@@ -1,4 +1,5 @@
-import type { AuthObject, ClerkClient } from '@clerk/backend';
+import type { ClerkClient } from '@clerk/backend';
+import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
 
 import type { ClerkTool } from './clerk-tool';
 
@@ -12,7 +13,7 @@ export type ToolkitParams = {
    * @default {}
    */
   authContext?: Pick<
-    AuthObject,
+    SignedInAuthObject | SignedOutAuthObject,
     'userId' | 'sessionId' | 'sessionClaims' | 'orgId' | 'orgRole' | 'orgSlug' | 'orgPermissions' | 'actor'
   >;
   /**

packages/backend/src/__tests__/exports.test.ts

@@ -22,6 +22,8 @@ describe('subpath /errors exports', () => {
   it('should not include a breaking change', () => {
     expect(Object.keys(errorExports).sort()).toMatchInlineSnapshot(`
       [
+        "MachineTokenVerificationError",
+        "MachineTokenVerificationErrorCode",
         "SignJWTError",
         "TokenVerificationError",
         "TokenVerificationErrorAction",
@@ -37,18 +39,24 @@ describe('subpath /internal exports', () => {
     expect(Object.keys(internalExports).sort()).toMatchInlineSnapshot(`
       [
         "AuthStatus",
+        "authenticatedMachineObject",
         "constants",
         "createAuthenticateRequest",
         "createClerkRequest",
         "createRedirect",
         "debugRequestState",
         "decorateObjectWithResources",
+        "getMachineTokenType",
+        "isMachineToken",
+        "isTokenTypeAccepted",
         "makeAuthObjectSerializable",
         "reverificationError",
         "reverificationErrorResponse",
         "signedInAuthObject",
         "signedOutAuthObject",
         "stripPrivateDataFromObject",
+        "unauthenticatedMachineObject",
+        "verifyMachineAuthToken",
       ]
     `);
   });

packages/backend/src/api/endpoints/APIKeysApi.ts

@@ -0,0 +1,15 @@
+import { joinPaths } from '../../util/path';
+import type { APIKey } from '../resources/APIKey';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/api_keys';
+
+export class APIKeysAPI extends AbstractAPI {
+  async verifySecret(secret: string) {
+    return this.request<APIKey>({
+      method: 'POST',
+      path: joinPaths(basePath, 'verify'),
+      bodyParams: { secret },
+    });
+  }
+}

packages/backend/src/api/endpoints/IdPOAuthAccessTokenApi.ts

@@ -0,0 +1,15 @@
+import { joinPaths } from '../../util/path';
+import type { IdPOAuthAccessToken } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/oauth_applications/access_tokens';
+
+export class IdPOAuthAccessTokenApi extends AbstractAPI {
+  async verifySecret(secret: string) {
+    return this.request<IdPOAuthAccessToken>({
+      method: 'POST',
+      path: joinPaths(basePath, 'verify'),
+      bodyParams: { secret },
+    });
+  }
+}

packages/backend/src/api/endpoints/MachineTokensApi.ts

@@ -0,0 +1,15 @@
+import { joinPaths } from '../../util/path';
+import type { MachineToken } from '../resources/MachineToken';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/m2m_tokens';
+
+export class MachineTokensApi extends AbstractAPI {
+  async verifySecret(secret: string) {
+    return this.request<MachineToken>({
+      method: 'POST',
+      path: joinPaths(basePath, 'verify'),
+      bodyParams: { secret },
+    });
+  }
+}

packages/backend/src/api/endpoints/index.ts

@@ -2,13 +2,16 @@ export * from './ActorTokenApi';
 export * from './AccountlessApplicationsAPI';
 export * from './AbstractApi';
 export * from './AllowlistIdentifierApi';
+export * from './APIKeysApi';
 export * from './BetaFeaturesApi';
 export * from './BlocklistIdentifierApi';
 export * from './ClientApi';
 export * from './DomainApi';
 export * from './EmailAddressApi';
+export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';
+export * from './MachineTokensApi';
 export * from './JwksApi';
 export * from './JwtTemplatesApi';
 export * from './OrganizationApi';

packages/backend/src/api/factory.ts

@@ -2,15 +2,18 @@ import {
   AccountlessApplicationAPI,
   ActorTokenAPI,
   AllowlistIdentifierAPI,
+  APIKeysAPI,
   BetaFeaturesAPI,
   BlocklistIdentifierAPI,
   ClientAPI,
   DomainAPI,
   EmailAddressAPI,
+  IdPOAuthAccessTokenApi,
   InstanceAPI,
   InvitationAPI,
   JwksAPI,
   JwtTemplatesApi,
+  MachineTokensApi,
   OAuthApplicationsApi,
   OrganizationAPI,
   PhoneNumberAPI,
@@ -47,6 +50,25 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
     emailAddresses: new EmailAddressAPI(request),
     instance: new InstanceAPI(request),
     invitations: new InvitationAPI(request),
+    // TODO: Remove this once we add a version to bapi-proxy
+    machineTokens: new MachineTokensApi(
+      buildRequest({
+        ...options,
+        apiVersion: '/',
+      }),
+    ),
+    idPOAuthAccessToken: new IdPOAuthAccessTokenApi(
+      buildRequest({
+        ...options,
+        apiVersion: '/',
+      }),
+    ),
+    apiKeys: new APIKeysAPI(
+      buildRequest({
+        ...options,
+        apiVersion: '/',
+      }),
+    ),
     jwks: new JwksAPI(request),
     jwtTemplates: new JwtTemplatesApi(request),
     oauthApplications: new OAuthApplicationsApi(request),

packages/backend/src/api/resources/APIKey.ts

@@ -0,0 +1,41 @@
+import type { APIKeyJSON } from './JSON';
+
+export class APIKey {
+  constructor(
+    readonly id: string,
+    readonly type: string,
+    readonly name: string,
+    readonly subject: string,
+    readonly scopes: string[],
+    readonly claims: Record<string, string> | null,
+    readonly revoked: boolean,
+    readonly revocationReason: string | null,
+    readonly expired: boolean,
+    readonly expiration: number | null,
+    readonly createdBy: string | null,
+    readonly creationReason: string | null,
+    readonly secondsUntilExpiration: number | null,
+    readonly createdAt: number,
+    readonly updatedAt: number,
+  ) {}
+
+  static fromJSON(data: APIKeyJSON) {
+    return new APIKey(
+      data.id,
+      data.type,
+      data.name,
+      data.subject,
+      data.scopes,
+      data.claims,
+      data.revoked,
+      data.revocation_reason,
+      data.expired,
+      data.expiration,
+      data.created_by,
+      data.creation_reason,
+      data.seconds_until_expiration,
+      data.created_at,
+      data.updated_at,
+    );
+  }
+}

packages/backend/src/api/resources/Deserializer.ts

@@ -1,18 +1,21 @@
 import {
   ActorToken,
   AllowlistIdentifier,
+  APIKey,
   BlocklistIdentifier,
   Client,
   Cookies,
   DeletedObject,
   Domain,
   Email,
   EmailAddress,
+  IdPOAuthAccessToken,
   Instance,
   InstanceRestrictions,
   InstanceSettings,
   Invitation,
   JwtTemplate,
+  MachineToken,
   OauthAccessToken,
   OAuthApplication,
   Organization,
@@ -85,6 +88,8 @@ function jsonToObject(item: any): any {
       return ActorToken.fromJSON(item);
     case ObjectType.AllowlistIdentifier:
       return AllowlistIdentifier.fromJSON(item);
+    case ObjectType.ApiKey:
+      return APIKey.fromJSON(item);
     case ObjectType.BlocklistIdentifier:
       return BlocklistIdentifier.fromJSON(item);
     case ObjectType.Client:
@@ -97,6 +102,8 @@ function jsonToObject(item: any): any {
       return EmailAddress.fromJSON(item);
     case ObjectType.Email:
       return Email.fromJSON(item);
+    case ObjectType.IdpOAuthAccessToken:
+      return IdPOAuthAccessToken.fromJSON(item);
     case ObjectType.Instance:
       return Instance.fromJSON(item);
     case ObjectType.InstanceRestrictions:
@@ -107,6 +114,8 @@ function jsonToObject(item: any): any {
       return Invitation.fromJSON(item);
     case ObjectType.JwtTemplate:
       return JwtTemplate.fromJSON(item);
+    case ObjectType.MachineToken:
+      return MachineToken.fromJSON(item);
     case ObjectType.OauthAccessToken:
       return OauthAccessToken.fromJSON(item);
     case ObjectType.OAuthApplication:

packages/backend/src/api/resources/IdPOAuthAccessToken.ts

@@ -0,0 +1,35 @@
+import type { IdPOAuthAccessTokenJSON } from './JSON';
+
+export class IdPOAuthAccessToken {
+  constructor(
+    readonly id: string,
+    readonly clientId: string,
+    readonly type: string,
+    readonly name: string,
+    readonly subject: string,
+    readonly scopes: string[],
+    readonly revoked: boolean,
+    readonly revocationReason: string | null,
+    readonly expired: boolean,
+    readonly expiration: number | null,
+    readonly createdAt: number,
+    readonly updatedAt: number,
+  ) {}
+
+  static fromJSON(data: IdPOAuthAccessTokenJSON) {
+    return new IdPOAuthAccessToken(
+      data.id,
+      data.client_id,
+      data.type,
+      data.name,
+      data.subject,
+      data.scopes,
+      data.revoked,
+      data.revocation_reason,
+      data.expired,
+      data.expiration,
+      data.created_at,
+      data.updated_at,
+    );
+  }
+}

packages/backend/src/api/resources/JSON.ts

@@ -20,6 +20,7 @@ export const ObjectType = {
   AccountlessApplication: 'accountless_application',
   ActorToken: 'actor_token',
   AllowlistIdentifier: 'allowlist_identifier',
+  ApiKey: 'api_key',
   BlocklistIdentifier: 'blocklist_identifier',
   Client: 'client',
   Cookies: 'cookies',
@@ -33,8 +34,10 @@ export const ObjectType = {
   InstanceRestrictions: 'instance_restrictions',
   InstanceSettings: 'instance_settings',
   Invitation: 'invitation',
+  MachineToken: 'machine_token',
   JwtTemplate: 'jwt_template',
   OauthAccessToken: 'oauth_access_token',
+  IdpOAuthAccessToken: 'clerk_idp_oauth_access_token',
   OAuthApplication: 'oauth_application',
   Organization: 'organization',
   OrganizationDomain: 'organization_domain',
@@ -672,6 +675,55 @@ export interface SamlAccountConnectionJSON extends ClerkResourceJSON {
   updated_at: number;
 }
 
+export interface MachineTokenJSON extends ClerkResourceJSON {
+  object: typeof ObjectType.MachineToken;
+  name: string;
+  subject: string;
+  scopes: string[];
+  claims: Record<string, string> | null;
+  revoked: boolean;
+  revocation_reason: string | null;
+  expired: boolean;
+  expiration: number | null;
+  created_by: string | null;
+  creation_reason: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface APIKeyJSON extends ClerkResourceJSON {
+  object: typeof ObjectType.ApiKey;
+  type: string;
+  name: string;
+  subject: string;
+  scopes: string[];
+  claims: Record<string, string> | null;
+  revoked: boolean;
+  revocation_reason: string | null;
+  expired: boolean;
+  expiration: number | null;
+  created_by: string | null;
+  creation_reason: string | null;
+  seconds_until_expiration: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface IdPOAuthAccessTokenJSON extends ClerkResourceJSON {
+  object: typeof ObjectType.IdpOAuthAccessToken;
+  client_id: string;
+  type: string;
+  name: string;
+  subject: string;
+  scopes: string[];
+  revoked: boolean;
+  revocation_reason: string | null;
+  expired: boolean;
+  expiration: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
 export interface WebhooksSvixJSON {
   svix_url: string;
 }

packages/backend/src/api/resources/MachineToken.ts

@@ -0,0 +1,37 @@
+import type { MachineTokenJSON } from './JSON';
+
+export class MachineToken {
+  constructor(
+    readonly id: string,
+    readonly name: string,
+    readonly subject: string,
+    readonly scopes: string[],
+    readonly claims: Record<string, string> | null,
+    readonly revoked: boolean,
+    readonly revocationReason: string | null,
+    readonly expired: boolean,
+    readonly expiration: number | null,
+    readonly createdBy: string | null,
+    readonly creationReason: string | null,
+    readonly createdAt: number,
+    readonly updatedAt: number,
+  ) {}
+
+  static fromJSON(data: MachineTokenJSON) {
+    return new MachineToken(
+      data.id,
+      data.name,
+      data.subject,
+      data.scopes,
+      data.claims,
+      data.revoked,
+      data.revocation_reason,
+      data.expired,
+      data.expiration,
+      data.created_by,
+      data.creation_reason,
+      data.created_at,
+      data.updated_at,
+    );
+  }
+}