Differential D20975 Diff 49977 src/aphront/writeguard/AphrontWriteGuard.php

Changeset View

Standalone View

src/aphront/writeguard/AphrontWriteGuard.php

This file was added.

				<?php

				/**
				* Guard writes against CSRF. The Aphront structure takes care of most of this
				* for you, you just need to call:
				*
				* AphrontWriteGuard::willWrite();
				*
				* ...before executing a write against any new kind of storage engine. MySQL
				* databases and the default file storage engines are already covered, but if
				* you introduce new types of datastores make sure their writes are guarded. If
				* you don't guard writes and make a mistake doing CSRF checks in a controller,
				* a CSRF vulnerability can escape undetected.
				*
				* If you need to execute writes on a page which doesn't have CSRF tokens (for
				* example, because you need to do logging), you can temporarily disable the
				* write guard by calling:
				*
				* AphrontWriteGuard::beginUnguardedWrites();
				* do_logging_write();
				* AphrontWriteGuard::endUnguardedWrites();
				*
				* This is dangerous, because it disables the backup layer of CSRF protection
				* this class provides. You should need this only very, very rarely.
				*
				* @task protect Protecting Writes
				* @task disable Disabling Protection
				* @task manage Managing Write Guards
				* @task internal Internals
				*/
				final class AphrontWriteGuard extends Phobject {

				private static $instance;
				private static $allowUnguardedWrites = false;

				private $callback;
				private $allowDepth = 0;


				/* -( Managing Write Guards )---------------------------------------------- */


				/**
				* Construct a new write guard for a request. Only one write guard may be
				* active at a time. You must explicitly call @{method:dispose} when you are
				* done with a write guard:
				*
				* $guard = new AphrontWriteGuard($callback);
				* // ...
				* $guard->dispose();
				*
				* Normally, you do not need to manage guards yourself -- the Aphront stack
				* handles it for you.
				*
				* This class accepts a callback, which will be invoked when a write is
				* attempted. The callback should validate the presence of a CSRF token in
				* the request, or abort the request (e.g., by throwing an exception) if a
				* valid token isn't present.
				*
				* @param callable CSRF callback.
				* @return this
				* @task manage
				*/
				public function __construct($callback) {
				if (self::$instance) {
				throw new Exception(
				pht(
				'An %s already exists. Dispose of the previous guard '.
				'before creating a new one.',
				__CLASS__));
				}
				if (self::$allowUnguardedWrites) {
				throw new Exception(
				pht(
				'An %s is being created in a context which permits '.
				'unguarded writes unconditionally. This is not allowed and '.
				'indicates a serious error.',
				__CLASS__));
				}
				$this->callback = $callback;
				self::$instance = $this;
				}


				/**
				* Dispose of the active write guard. You must call this method when you are
				* done with a write guard. You do not normally need to call this yourself.
				*
				* @return void
				* @task manage
				*/
				public function dispose() {
				if (!self::$instance) {
				throw new Exception(pht(
				'Attempting to dispose of write guard, but no write guard is active!'));
				}

				if ($this->allowDepth > 0) {
				throw new Exception(
				pht(
				'Imbalanced %s: more %s calls than %s calls.',
				__CLASS__,
				'beginUnguardedWrites()',
				'endUnguardedWrites()'));
				}
				self::$instance = null;
				}


				/**
				* Determine if there is an active write guard.
				*
				* @return bool
				* @task manage
				*/
				public static function isGuardActive() {
				return (bool)self::$instance;
				}

				/**
				* Return on instance of AphrontWriteGuard if it's active, or null
				*
				* @return AphrontWriteGuard\|null
				*/
				public static function getInstance() {
				return self::$instance;
				}


				/* -( Protecting Writes )-------------------------------------------------- */


				/**
				* Declare intention to perform a write, validating that writes are allowed.
				* You should call this method before executing a write whenever you implement
				* a new storage engine where information can be permanently kept.
				*
				* Writes are permitted if:
				*
				* - The request has valid CSRF tokens.
				* - Unguarded writes have been temporarily enabled by a call to
				* @{method:beginUnguardedWrites}.
				* - All write guarding has been disabled with
				* @{method:allowDangerousUnguardedWrites}.
				*
				* If none of these conditions are true, this method will throw and prevent
				* the write.
				*
				* @return void
				* @task protect
				*/
				public static function willWrite() {
				if (!self::$instance) {
				if (!self::$allowUnguardedWrites) {
				throw new Exception(
				pht(
				'Unguarded write! There must be an active %s to perform writes.',
				__CLASS__));
				} else {
				// Unguarded writes are being allowed unconditionally.
				return;
				}
				}

				$instance = self::$instance;
				if ($instance->allowDepth == 0) {
				call_user_func($instance->callback);
				}
				}


				/* -( Disabling Write Protection )----------------------------------------- */


				/**
				* Enter a scope which permits unguarded writes. This works like
				* @{method:beginUnguardedWrites} but returns an object which will end
				* the unguarded write scope when its __destruct() method is called. This
				* is useful to more easily handle exceptions correctly in unguarded write
				* blocks:
				*
				* // Restores the guard even if do_logging() throws.
				* function unguarded_scope() {
				* $unguarded = AphrontWriteGuard::beginScopedUnguardedWrites();
				* do_logging();
				* }
				*
				* @return AphrontScopedUnguardedWriteCapability Object which ends unguarded
				* writes when it leaves scope.
				* @task disable
				*/
				public static function beginScopedUnguardedWrites() {
				self::beginUnguardedWrites();
				return new AphrontScopedUnguardedWriteCapability();
				}


				/**
				* Begin a block which permits unguarded writes. You should use this very
				* sparingly, and only for things like logging where CSRF is not a concern.
				*
				* You must pair every call to @{method:beginUnguardedWrites} with a call to
				* @{method:endUnguardedWrites}:
				*
				* AphrontWriteGuard::beginUnguardedWrites();
				* do_logging();
				* AphrontWriteGuard::endUnguardedWrites();
				*
				* @return void
				* @task disable
				*/
				public static function beginUnguardedWrites() {
				if (!self::$instance) {
				return;
				}
				self::$instance->allowDepth++;
				}

				/**
				* Declare that you have finished performing unguarded writes. You must
				* call this exactly once for each call to @{method:beginUnguardedWrites}.
				*
				* @return void
				* @task disable
				*/
				public static function endUnguardedWrites() {
				if (!self::$instance) {
				return;
				}
				if (self::$instance->allowDepth <= 0) {
				throw new Exception(
				pht(
				'Imbalanced %s: more %s calls than %s calls.',
				__CLASS__,
				'endUnguardedWrites()',
				'beginUnguardedWrites()'));
				}
				self::$instance->allowDepth--;
				}


				/**
				* Allow execution of unguarded writes. This is ONLY appropriate for use in
				* script contexts or other contexts where you are guaranteed to never be
				* vulnerable to CSRF concerns. Calling this method is EXTREMELY DANGEROUS
				* if you do not understand the consequences.
				*
				* If you need to perform unguarded writes on an otherwise guarded workflow
				* which is vulnerable to CSRF, use @{method:beginUnguardedWrites}.
				*
				* @return void
				* @task disable
				*/
				public static function allowDangerousUnguardedWrites($allow) {
				if (self::$instance) {
				throw new Exception(
				pht(
				'You can not unconditionally disable %s by calling %s while a write '.
				'guard is active. Use %s to temporarily allow unguarded writes.',
				__CLASS__,
				__FUNCTION__.'()',
				'beginUnguardedWrites()'));
				}
				self::$allowUnguardedWrites = true;
				}

				}