lee/puter
1
0
Fork 0
mirror of https://github.com/HeyPuter/puter.git synced 2026-09-23 21:56:57 +00:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

Added reference documentation for: src/backend/src/services/auth/Actor.js

Browse Source
This commit is contained in:
Andrei Onel
2025-08-12 00:32:13 +03:00
parent 1e720a7aca
commit eb55af59c8
1 changed files with 146 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/backend/src/services/auth/Actor.js
+146 -51
View File
@@ -31,11 +31,11 @@ const PRIVATE_UID_SECRET = config.private_uid_secret
/**
* Represents an Actor in the system, extending functionality from AdvancedBase.
* The Actor class is responsible for managing actor instances, including
* creating new actors, generating unique identifiers, and handling related types
* that represent different roles within the context of the application.
*/
* Represents an Actor in the system, extending functionality from AdvancedBase.
* The Actor class is responsible for managing actor instances, including
* creating new actors, generating unique identifiers, and handling related types
* that represent different roles within the context of the application.
*/
class Actor extends AdvancedBase {
static MODULES = {
uuidv5: require('uuid').v5,
@@ -43,9 +43,9 @@ class Actor extends AdvancedBase {
}
static system_actor_ = null;
/**
* Retrieves the system actor instance, creating it if it doesn't exist.
*
* This static method ensures that there is only one instance of the system actor.
* If the system actor has not yet been created, it will be instantiated with a
* new SystemActorType.
@@ -61,6 +61,16 @@ class Actor extends AdvancedBase {
return this.system_actor_;
}
/**
* Creates a new Actor instance with the specified type and parameters.
* Resolves user and app references from UIDs if provided in the parameters.
*
* @param {Function} type - The ActorType constructor to instantiate.
* @param {Object} params - Parameters for the actor type.
* @param {string} [params.user_uid] - UUID of the user to resolve.
* @param {string} [params.app_uid] - UID of the app to resolve.
* @returns {Promise<Actor>} A new Actor instance.
*/
static async create (type, params) {
params = { ...params };
if ( params.user_uid ) {
@@ -75,12 +85,12 @@ class Actor extends AdvancedBase {
}
/**
* Initializes the Actor instance with the provided parameters.
* This constructor assigns object properties from the input object to the instance.
*
* @param {Object} o - The object containing actor parameters.
* @param {...any} a - Additional arguments passed to the parent class constructor.
*/
* Initializes the Actor instance with the provided parameters.
* This constructor assigns object properties from the input object to the instance.
*
* @param {Object} o - The object containing actor parameters.
* @param {...any} a - Additional arguments passed to the parent class constructor.
*/
constructor (o, ...a) {
super(o, ...a);
for ( const k in o ) {
@@ -88,10 +98,20 @@ class Actor extends AdvancedBase {
}
}
/**
* Gets the unique identifier for this actor.
*
* @returns {string} The actor's UID from its type.
*/
get uid () {
return this.type.uid;
}
/**
* Returns fields suitable for logging this actor.
*
* @returns {Object} Object containing UID and optionally username for logging.
*/
toLogFields () {
return {
uid: this.type.uid,
@@ -102,13 +122,13 @@ class Actor extends AdvancedBase {
}
/**
* Generates a cryptographically-secure deterministic UUID
* from an actor's UID. The generated UUID is derived by
* applying SHA-256 HMAC to the actor's UID using a secret,
* then formatting the result as a UUID V5.
*
* @returns {string} The derived UUID corresponding to the actor's UID.
*/
* Generates a cryptographically-secure deterministic UUID
* from an actor's UID. The generated UUID is derived by
* applying SHA-256 HMAC to the actor's UID using a secret,
* then formatting the result as a UUID V5.
*
* @returns {string} The derived UUID corresponding to the actor's UID.
*/
get private_uid () {
// Pass the UUID through SHA-2 first because UUIDv5
// is not cryptographically secure (it uses SHA-1)
@@ -139,6 +159,12 @@ class Actor extends AdvancedBase {
});
}
/**
* Creates a related actor of the specified type based on the current actor.
*
* @param {Function} type_class - The ActorType class to create a related actor for.
* @returns {Actor} A new Actor instance with the related type.
*/
get_related_actor (type_class) {
const actor = this.clone();
actor.type = this.type.get_related_type(type_class);
@@ -146,7 +172,16 @@ class Actor extends AdvancedBase {
}
}
/**
* Base class for all actor types in the system.
* Provides common initialization functionality for actor type instances.
*/
class ActorType {
/**
* Initializes the ActorType with the provided properties.
*
* @param {Object} o - Object containing properties to assign to this instance.
*/
constructor (o) {
for ( const k in o ) {
this[k] = o[k];
@@ -155,15 +190,28 @@ class ActorType {
}
/**
* Class representing the system actor type within the actor framework.
* This type serves as a specific implementation of an actor that
* represents a system-level entity and provides methods for UID retrieval
* and related type management.
*/
* Class representing the system actor type within the actor framework.
* This type serves as a specific implementation of an actor that
* represents a system-level entity and provides methods for UID retrieval
* and related type management.
*/
class SystemActorType extends ActorType {
/**
* Gets the unique identifier for the system actor.
*
* @returns {string} Always returns 'system'.
*/
get uid () {
return 'system';
}
/**
* Gets a related actor type for the system actor.
*
* @param {Function} type_class - The ActorType class to get a related type for.
* @returns {SystemActorType} Returns this instance if type_class is SystemActorType.
* @throws {Error} If the requested type_class is not supported.
*/
get_related_type (type_class) {
if ( type_class === SystemActorType ) {
return this;
@@ -174,14 +222,27 @@ class SystemActorType extends ActorType {
/**
* Represents the type of a User Actor in the system, allowing operations and relations
* specific to user actors. This class extends the base functionality to uniquely identify
* user actors and define how they relate to other types of actors within the system.
*/
* Represents the type of a User Actor in the system, allowing operations and relations
* specific to user actors. This class extends the base functionality to uniquely identify
* user actors and define how they relate to other types of actors within the system.
*/
class UserActorType extends ActorType {
/**
* Gets the unique identifier for the user actor.
*
* @returns {string} The UID in format 'user:{uuid}'.
*/
get uid () {
return 'user:' + this.user.uuid;
}
/**
* Gets a related actor type for the user actor.
*
* @param {Function} type_class - The ActorType class to get a related type for.
* @returns {UserActorType} Returns this instance if type_class is UserActorType.
* @throws {Error} If the requested type_class is not supported.
*/
get_related_type (type_class) {
if ( type_class === UserActorType ) {
return this;
@@ -189,16 +250,30 @@ class UserActorType extends ActorType {
throw new Error(`cannot get ${type_class.name} from ${this.constructor.name}`)
}
}
/**
* Represents a user actor type in the application. This class defines the structure
* and behavior specific to user actors, including obtaining unique identifiers and
* retrieving related actor types. It extends the base actor type functionality
* to cater to user-specific needs.
*/
* Represents a user actor type in the application. This class defines the structure
* and behavior specific to user actors, including obtaining unique identifiers and
* retrieving related actor types. It extends the base actor type functionality
* to cater to user-specific needs.
*/
class AppUnderUserActorType extends ActorType {
/**
* Gets the unique identifier for the app-under-user actor.
*
* @returns {string} The UID in format 'app-under-user:{user_uuid}:{app_uid}'.
*/
get uid () {
return 'app-under-user:' + this.user.uuid + ':' + this.app.uid;
}
/**
* Gets a related actor type for the app-under-user actor.
*
* @param {Function} type_class - The ActorType class to get a related type for.
* @returns {UserActorType|AppUnderUserActorType} The related actor type instance.
* @throws {Error} If the requested type_class is not supported.
*/
get_related_type (type_class) {
if ( type_class === UserActorType ) {
return new UserActorType({ user: this.user });
@@ -212,26 +287,33 @@ class AppUnderUserActorType extends ActorType {
/**
* Represents the type of access tokens in the system.
* An AccessTokenActorType associates an authorizer and an authorized actor
* with a string token, facilitating permission checks and identity management.
*/
* Represents the type of access tokens in the system.
* An AccessTokenActorType associates an authorizer and an authorized actor
* with a string token, facilitating permission checks and identity management.
*/
class AccessTokenActorType extends ActorType {
// authorizer: an Actor who authorized the token
// authorized: an Actor who is authorized by the token
// token: a string
/**
* Gets the unique identifier for the access token actor.
* The UID is constructed based on the authorizer's UID, the authorized actor's UID (if available),
* and the token string. This UID format is useful for identifying the access token's context.
*
* @returns {string} The generated UID for the access token.
*/
get uid () {
return 'access-token:' + this.authorizer.uid +
':' + ( this.authorized?.uid ?? '<none>' ) +
':' + this.token;
}
/**
* Generate a unique identifier (UID) for the access token.
* The UID is constructed based on the authorizer's UID, the authorized actor's UID (if available),
* and the token string. This UID format is useful for identifying the access token's context.
* Throws an error as getting related actors is not supported for access tokens.
* This would be dangerous because of ambiguity between authorizer and authorized.
*
* @returns {string} The generated UID for the access token.
* @throws {Error} Always throws an error indicating this operation is not supported.
*/
get_related_actor () {
// This would be dangerous because of ambiguity
@@ -242,29 +324,42 @@ class AccessTokenActorType extends ActorType {
/**
* Represents a Site Actor Type, which encapsulates information about a site-specific actor.
* This class is used to manage details related to the site and implement functionalities
* pertinent to site-level operations and interactions in the actor framework.
*/
* Represents a Site Actor Type, which encapsulates information about a site-specific actor.
* This class is used to manage details related to the site and implement functionalities
* pertinent to site-level operations and interactions in the actor framework.
*/
class SiteActorType {
/**
* Constructor for the SiteActorType class.
* Initializes a new instance of SiteActorType with the provided properties.
*
* @param {Object} o - The properties to initialize the SiteActorType with.
* @param {...*} a - Additional arguments.
*/
* Constructor for the SiteActorType class.
* Initializes a new instance of SiteActorType with the provided properties.
*
* @param {Object} o - The properties to initialize the SiteActorType with.
* @param {...*} a - Additional arguments.
*/
constructor (o, ...a) {
for ( const k in o ) {
this[k] = o[k];
}
}
/**
* Gets the unique identifier for the site actor.
*
* @returns {string} The UID in format 'site:{site_name}'.
*/
get uid () {
return `site:` + this.site.name
}
}
/**
* Adapts various input types to a proper Actor instance.
* If no actor is provided, attempts to get one from the current context.
* Handles legacy user objects by wrapping them in UserActorType.
*
* @param {Actor|Object} [actor] - The actor to adapt, or undefined to use context.
* @returns {Actor} A properly formatted Actor instance.
*/
Actor.adapt = function (actor) {
actor = actor || Context.get('actor');