chore: add security functions

security/functions.php

@@ -13,3 +13,41 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+
+namespace Castor\Security;
+
+use Castor\Context;
+use Castor\MissingContextValue;
+
+/** @internal  */
+enum CtxKey
+{
+    /** @internal  */
+    case Principal;
+}
+
+function withPrincipal(Context $ctx, Principal $principal): Context
+{
+    return Context\withValue($ctx, CtxKey::Principal, $principal);
+}
+
+function getPrincipal(Context $ctx): Principal
+{
+    return $ctx->value(CtxKey::Principal) ??
+        throw MissingContextValue::forKey(CtxKey::Principal);
+}
+
+function lookupPrincipal(Context $ctx): ?Principal
+{
+    return $ctx->value(CtxKey::Principal);
+}
+
+function getIdentity(Context $ctx): Identity
+{
+    return getPrincipal($ctx)->getIdentity();
+}
+
+function lookupIdentity(Context $ctx): ?Identity
+{
+    return lookupPrincipal($ctx)?->getIdentity();
+}