activitypub / includes / oauth / class-scope.php

class-scope.php in ActivityPub 8.1.1, at includes/oauth/class-scope.php

191 lines 4.0 KB

Raw Download Zip

1	<?php
2	/**
3	* OAuth 2.0 Scope definitions for ActivityPub C2S.
4	*
5	* @package Activitypub
6	*/
7
8	namespace Activitypub\OAuth;
9
10	/**
11	* Scope class for OAuth 2.0 scope management.
12	*
13	* Defines available scopes and provides validation methods.
14	*/
15	class Scope {
16	/**
17	* Read access scope - read actor profile, collections, and objects.
18	*/
19	const READ = 'read';
20
21	/**
22	* Write access scope - create activities via POST to outbox.
23	*/
24	const WRITE = 'write';
25
26	/**
27	* Follow access scope - manage following relationships.
28	*/
29	const FOLLOW = 'follow';
30
31	/**
32	* Push access scope - subscribe to SSE streams.
33	*/
34	const PUSH = 'push';
35
36	/**
37	* Profile access scope - edit actor profile.
38	*/
39	const PROFILE = 'profile';
40
41	/**
42	* All available scopes.
43	*
44	* @var array
45	*/
46	const ALL = array(
47	self::READ,
48	self::WRITE,
49	self::FOLLOW,
50	self::PUSH,
51	self::PROFILE,
52	);
53
54	/**
55	* Human-readable descriptions for each scope.
56	*
57	* @var array
58	*/
59	const DESCRIPTIONS = array(
60	self::READ => 'Read actor profile, collections, and objects',
61	self::WRITE => 'Create activities via POST to outbox',
62	self::FOLLOW => 'Manage following relationships',
63	self::PUSH => 'Subscribe to real-time event streams',
64	self::PROFILE => 'Edit actor profile',
65	);
66
67	/**
68	* Default scopes when none are requested.
69	*
70	* Defaults to read-only to prevent granting write access without
71	* explicit scope request (fail-closed on access control).
72	*
73	* @var array
74	*/
75	const DEFAULT_SCOPES = array(
76	self::READ,
77	);
78
79	/**
80	* Validate and filter requested scopes.
81	*
82	* @param string\|array $scopes The requested scopes (space-separated string or array).
83	* @return array Valid scopes.
84	*/
85	public static function validate( $scopes ) {
86	if ( is_string( $scopes ) ) {
87	$scopes = self::parse( $scopes );
88	}
89
90	if ( ! is_array( $scopes ) ) {
91	return self::DEFAULT_SCOPES;
92	}
93
94	$valid_scopes = array_intersect( $scopes, self::ALL );
95
96	if ( empty( $valid_scopes ) ) {
97	return self::DEFAULT_SCOPES;
98	}
99
100	return array_values( $valid_scopes );
101	}
102
103	/**
104	* Parse a space-separated scope string to array.
105	*
106	* @param string $scope_string Space-separated scopes.
107	* @return array Scope array.
108	*/
109	public static function parse( $scope_string ) {
110	if ( empty( $scope_string ) \|\| ! is_string( $scope_string ) ) {
111	return array();
112	}
113
114	$scopes = preg_split( '/\s+/', trim( $scope_string ) );
115
116	return array_filter( array_map( 'trim', $scopes ) );
117	}
118
119	/**
120	* Convert scopes array to space-separated string.
121	*
122	* @param array $scopes The scopes array.
123	* @return string Space-separated scope string.
124	*/
125	public static function to_string( $scopes ) {
126	if ( ! is_array( $scopes ) ) {
127	return '';
128	}
129
130	return implode( ' ', $scopes );
131	}
132
133	/**
134	* Check if a scope is valid.
135	*
136	* @param string $scope The scope to check.
137	* @return bool True if valid, false otherwise.
138	*/
139	public static function is_valid( $scope ) {
140	return in_array( $scope, self::ALL, true );
141	}
142
143	/**
144	* Get the description for a scope.
145	*
146	* @param string $scope The scope.
147	* @return string The description or empty string if not found.
148	*/
149	public static function get_description( $scope ) {
150	return self::DESCRIPTIONS[ $scope ] ?? '';
151	}
152
153	/**
154	* Get all scopes with their descriptions.
155	*
156	* @return array Associative array of scope => description.
157	*/
158	public static function get_all_with_descriptions() {
159	return self::DESCRIPTIONS;
160	}
161
162	/**
163	* Check if scopes contain a specific scope.
164	*
165	* @param array $scopes The scopes to check.
166	* @param string $scope The scope to look for.
167	* @return bool True if the scope is present.
168	*/
169	public static function contains( $scopes, $scope ) {
170	return is_array( $scopes ) && in_array( $scope, $scopes, true );
171	}
172
173	/**
174	* Sanitize callback for scope storage.
175	*
176	* @param mixed $value The value to sanitize.
177	* @return array Sanitized scopes array.
178	*/
179	public static function sanitize( $value ) {
180	if ( is_string( $value ) ) {
181	$value = self::parse( $value );
182	}
183
184	if ( ! is_array( $value ) ) {
185	return array();
186	}
187
188	return self::validate( $value );
189	}
190	}
191