feat: Add comprehensive documentation suite and reorganize project structure

- Created complete documentation in docs/ directory - Added PROJECT_OVERVIEW.md with feature highlights and getting started guide - Added ARCHITECTURE.md with system design and technical details - Added SECURITY.md with comprehensive security implementation guide - Added DEVELOPMENT.md with development workflows and best practices - Added DEPLOYMENT.md with production deployment instructions - Added API.md with complete REST API documentation - Added CONTRIBUTING.md with contribution guidelines - Added CHANGELOG.md with version history and migration notes - Reorganized all documentation files into docs/ directory for better organization - Updated README.md with proper documentation links and quick navigation - Enhanced project structure with professional documentation standards
2025-10-21 00:39:45 -07:00
commit 0b7e2d0a5b
6080 changed files with 1332936 additions and 0 deletions
--- a/Google/Auth/ComputeEngine.php
+++ b/Google/Auth/ComputeEngine.php
@@ -0,0 +1,146 @@
+<?php
+/*
+ * Copyright 2014 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+if (!class_exists('Google_Client')) {
+  require_once dirname(__FILE__) . '/../autoload.php';
+}
+
+/**
+ * Authentication via built-in Compute Engine service accounts.
+ * The instance must be pre-configured with a service account
+ * and the appropriate scopes.
+ * @author Jonathan Parrott <jon.wayne.parrott@gmail.com>
+ */
+class Google_Auth_ComputeEngine extends Google_Auth_Abstract
+{
+  const METADATA_AUTH_URL =
+      'http://metadata/computeMetadata/v1/instance/service-accounts/default/token';
+  private $client;
+  private $token;
+
+  public function __construct(Google_Client $client, $config = null)
+  {
+    $this->client = $client;
+  }
+
+  /**
+   * Perform an authenticated / signed apiHttpRequest.
+   * This function takes the apiHttpRequest, calls apiAuth->sign on it
+   * (which can modify the request in what ever way fits the auth mechanism)
+   * and then calls apiCurlIO::makeRequest on the signed request
+   *
+   * @param Google_Http_Request $request
+   * @return Google_Http_Request The resulting HTTP response including the
+   * responseHttpCode, responseHeaders and responseBody.
+   */
+  public function authenticatedRequest(Google_Http_Request $request)
+  {
+    $request = $this->sign($request);
+    return $this->client->getIo()->makeRequest($request);
+  }
+
+  /**
+   * @param string $token
+   * @throws Google_Auth_Exception
+   */
+  public function setAccessToken($token)
+  {
+    $token = json_decode($token, true);
+    if ($token == null) {
+      throw new Google_Auth_Exception('Could not json decode the token');
+    }
+    if (! isset($token['access_token'])) {
+      throw new Google_Auth_Exception("Invalid token format");
+    }
+    $token['created'] = time();
+    $this->token = $token;
+  }
+
+  public function getAccessToken()
+  {
+    return json_encode($this->token);
+  }
+
+  /**
+   * Acquires a new access token from the compute engine metadata server.
+   * @throws Google_Auth_Exception
+   */
+  public function acquireAccessToken()
+  {
+    $request = new Google_Http_Request(
+        self::METADATA_AUTH_URL,
+        'GET',
+        array(
+          'Metadata-Flavor' => 'Google'
+        )
+    );
+    $request->disableGzip();
+    $response = $this->client->getIo()->makeRequest($request);
+
+    if ($response->getResponseHttpCode() == 200) {
+      $this->setAccessToken($response->getResponseBody());
+      $this->token['created'] = time();
+      return $this->getAccessToken();
+    } else {
+      throw new Google_Auth_Exception(
+          sprintf(
+              "Error fetching service account access token, message: '%s'",
+              $response->getResponseBody()
+          ),
+          $response->getResponseHttpCode()
+      );
+    }
+  }
+
+  /**
+   * Include an accessToken in a given apiHttpRequest.
+   * @param Google_Http_Request $request
+   * @return Google_Http_Request
+   * @throws Google_Auth_Exception
+   */
+  public function sign(Google_Http_Request $request)
+  {
+    if ($this->isAccessTokenExpired()) {
+      $this->acquireAccessToken();
+    }
+
+    $this->client->getLogger()->debug('Compute engine service account authentication');
+
+    $request->setRequestHeaders(
+        array('Authorization' => 'Bearer ' . $this->token['access_token'])
+    );
+
+    return $request;
+  }
+
+  /**
+   * Returns if the access_token is expired.
+   * @return bool Returns True if the access_token is expired.
+   */
+  public function isAccessTokenExpired()
+  {
+    if (!$this->token || !isset($this->token['created'])) {
+      return true;
+    }
+
+    // If the token is set to expire in the next 30 seconds.
+    $expired = ($this->token['created']
+        + ($this->token['expires_in'] - 30)) < time();
+
+    return $expired;
+  }
+}