Initial implementation

.github/workflows/test.yml

@@ -20,10 +20,10 @@ jobs:
           - 'high'
           - 'low'
         php:
-          - '7.4'
-          - '8.0'
           - '8.1'
           - '8.2'
+          - '8.3'
+          - '8.4-dev'
 
     steps:
       - name: Check out code

README.md

@@ -1,19 +1,105 @@
-# php-library-template
-Repository template for PHP libraries. Sets up composer, CI with Github Actions, and more.
+# SnapAuth PHP SDK
 
-## Git
-- Configures `.gitignore` for common excludes in a PHP library
+This is the official PHP SDK for [SnapAuth](https://www.snapauth.app).
 
-## Composer
-- Placeholders for library name, description, and PSR-4 autoloading
-- Scripts for testing
-- Requires current version of PHP
-- Includes testing tools (configured) as dev dependencies
+## Documentation
 
-## Testing and CI
-CI is configured using Github Actions.
+Full API and usage docs are available [at the official site](https://docs.snapauth.app/server.html#introduction).
 
-- PHPUnit `^9.3` with default configuration (`src`/`tests`).
-- The tests workflow uses a build matrix to test against multiple versions of PHP, and with high and low Composer dependencies installed
-- PHPStan with strict ruleset, max level, and the PHPUnit extension
-- PHP Code Sniffer configured with PSR-12
+## Installation
+
+```bash
+composer require snapauth/sdk
+```
+
+## Setup
+
+Get your _secret_ key from the [dashboard](https://dashboard.snapauth.app).
+Provide it to the `SnapAuth\Client` class:
+
+```php
+use SnapAuth\Client;
+
+$yourSecret = getenv('SNAPAUTH_SECRET_KEY');
+$snapAuth = new Client(secretKey: $yourSecret);
+```
+
+> [!TIP]
+> Secret keys are specific to an environment and domain.
+> We HIGHLY RECOMMEND using environment variables or another external storage mechanism.
+> Avoid committing them to version control, as this can more easily lead to compromise.
+
+## Usage
+
+### Registration
+
+Once you obtain a registration token from your frontend, use the `Client` to complete the process and attach it to the user:
+
+```php
+$token = 'value_from_frontend'; // $_POST['snapauth_token'] or similar
+$userInfo = [
+  'id' => 'your_user_id',
+  'handle' => 'your_user_handle',
+];
+$snapAuth->attachRegistration($token, $userInfo);
+```
+
+<!--
+Registration returns an `AttachResponse` object, which contains a credential identifier.
+You may store this information at your end, but it's not necessary in most cases.
+-->
+
+This activates the passkey and associates it with the user.
+`$userInfo` will be provided back to you during authentication, so you know who is signing in.
+
+`id` should be some sort of _stable_ identifer, like a database primary key.
+
+`handle` can be anything you want, or omitted entirely.
+It's a convenience during _client_ authentication so you don't need to look up the user id again.
+This would commonly be the value a user provides to sign in, such as a username or email.
+
+Both must be strings, and can be up to 255 characters long.
+Lookups during authentication are **case-insensitive**.
+
+> [!TIP]
+> We strongly ENCOURAGE you to obfuscate any possibly sensitive information, such as email addresses.
+> You can accomplish this by hashing the value.
+> Be aware that to use the handle during authentication, you will want to replicate the obfuscation procedure on your frontend.
+
+### Authentication
+
+Like registration, you will need to obtain a token from your frontend provided by the client SDK.
+
+Use the `verifyAuthToken` method to get information about the authentication process, in the form of an `AuthResponse` object.
+This object contains the previously-registered User `id` and `handle`.
+
+```php
+$token = 'value_from_frontend'; // $_POST['snapauth_token'] or similar
+$authInfo = $snapAuth->verifyAuthToken($token);
+
+// Specific to your application:
+$authenticatedUserId = $authInfo->user->id;
+
+// Laravel:
+use Illuminate\Support\Facades\Auth;
+Auth::loginUsingId($authenticatedUserId);
+```
+
+## Error Handling
+
+The SnapAuth SDK is written in a fail-secure manner, and will throw an exception if you're not on the successful path.
+This helps ensure that your integration is easy and reliable.
+
+You may choose to locally wrap API calls in a `try/catch` block, or let a general application-wide error handler deal with any exceptions.
+
+All SnapAuth exceptions are an `instanceof \SnapAuth\ApiError`.
+
+## Compatibility
+
+We follow semantic versioning, and limit backwards-incompatible changes to major versions (the X in X.Y.Z) only.
+
+The SnapAuth SDK is maintained for all versions of PHP with [current security support](https://www.php.net/supported-versions.php).
+Since Composer will platform-detect your currently-installed version of PHP, dropping support for older versions is _not_ considered a backwards compatibility break (but you may be unable to install newer versions until updating to a supported version of PHP).
+
+Anything marked as `@internal` or any `protected` or `private` method is not considered in scope for backwards-compatibility guarantees.
+Similarly, all methods should be treated as ones that may throw an exception, and as such new types of exceptions are not considered a BC break either.

composer.json

@@ -24,8 +24,9 @@
         }
     },
     "require": {
-        "php": "^7.4 || ^8.0",
-        "ext-curl": "*"
+        "php": "^8.1",
+        "ext-curl": "*",
+        "composer-runtime-api": "^2.2"
     },
     "require-dev": {
         "maglnet/composer-require-checker": "^2.0 || ^3.0 || ^4.0",

src/ApiError.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SnapAuth;
+
+use Exception;
+
+class ApiError extends Exception
+{
+}

src/AttachResponse.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SnapAuth;
+
+class AttachResponse
+{
+    // @phpstan-ignore-next-line
+    public function __construct(array $data)
+    {
+        // Intentionally empty for now - response format uncertain
+    }
+}

src/AuthResponse.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SnapAuth;
+
+class AuthResponse
+{
+    public readonly User $user;
+
+    // @phpstan-ignore-next-line
+    public function __construct(array $data)
+    {
+        $this->user = new User($data['user']);
+    }
+}

src/Client.php

@@ -0,0 +1,166 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SnapAuth;
+
+use Composer\InstalledVersions;
+use JsonException;
+use SensitiveParameter;
+
+use function assert;
+use function curl_close;
+use function curl_errno;
+use function curl_exec;
+use function curl_getinfo;
+use function curl_init;
+use function curl_setopt_array;
+use function curl_version;
+use function is_array;
+use function is_string;
+use function json_decode;
+use function json_encode;
+use function sprintf;
+use function strlen;
+
+use const CURLE_OK;
+use const CURLINFO_RESPONSE_CODE;
+use const CURLOPT_HTTPHEADER;
+use const CURLOPT_POST;
+use const CURLOPT_POSTFIELDS;
+use const CURLOPT_RETURNTRANSFER;
+use const CURLOPT_URL;
+use const JSON_THROW_ON_ERROR;
+
+/**
+ * SDK Prototype. This makes no attempt to short-circuit the network for
+ * internal use, forcing a completely dogfooded experience.
+ *
+ * TODO: make testable, presumably via PSR-18
+ * TODO: make an interface so the entire client can be mocked by developers
+ */
+class Client
+{
+    private const DEFAULT_API_HOST = 'https://api.snapauth.app';
+
+    public function __construct(
+        #[SensitiveParameter] private string $secretKey,
+        private string $apiHost = self::DEFAULT_API_HOST,
+    ) {
+        if (!str_starts_with($secretKey, 'secret_')) {
+            throw new ApiError(
+                'Invalid secret key. Please verify you copied the full value from the SnapAuth dashboard.',
+            );
+        }
+    }
+
+    /**
+     * return array{
+     *   user: array{
+     *     id: string,
+     *     handle: string,
+     *   },
+     * }
+     */
+    public function verifyAuthToken(string $authToken): AuthResponse
+    {
+        return $this->makeApiCall(
+            route: '/auth/verify',
+            data: [
+                'token' => $authToken,
+            ],
+            type: AuthResponse::class,
+        );
+    }
+
+    /**
+     * @param array{
+     *   handle: string,
+     *   id?: string,
+     * } $user
+     */
+    public function attachRegistration(string $regToken, array $user): AttachResponse
+    {
+        return $this->makeApiCall(
+            route: '/registration/attach',
+            data: [
+                'token' => $regToken,
+                'user' => $user,
+            ],
+            type: AttachResponse::class
+        );
+    }
+
+    /**
+     * @template T of object
+     * @param mixed[] $data
+     * @param class-string<T> $type
+     * @return T
+     */
+    private function makeApiCall(string $route, array $data, string $type): object
+    {
+        // TODO: PSR-xx
+        $json = json_encode($data, JSON_THROW_ON_ERROR);
+        $ch = curl_init();
+        curl_setopt_array($ch, [
+            CURLOPT_URL => sprintf('%s%s', $this->apiHost, $route),
+            CURLOPT_POST => 1,
+            CURLOPT_POSTFIELDS => $json,
+            // CURLOPT_VERBOSE => true,
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_HTTPHEADER => [
+                'Authorization: Basic ' . base64_encode(':' . $this->secretKey),
+                'Accept: application/json',
+                'Content-Type: application/json',
+                'Content-Length: ' . strlen($json),
+                sprintf(
+                    'User-Agent: php-sdk/%s curl/%s php/%s',
+                    InstalledVersions::getVersion('snapauth/sdk'),
+                    curl_version()['version'] ?? 'unknown',
+                    PHP_VERSION,
+                ),
+                sprintf('X-SDK: php/%s', InstalledVersions::getVersion('snapauth/sdk')),
+            ],
+        ]);
+
+        try {
+            $response = curl_exec($ch);
+            $errno = curl_errno($ch);
+            $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
+
+            if ($response === false || $errno !== CURLE_OK) {
+                $this->error();
+            }
+
+            if ($code >= 300) {
+                $this->error();
+            }
+            // Handle non-200s, non-JSON (severe upstream error)
+            assert(is_string($response));
+            $decoded = json_decode($response, true, flags: JSON_THROW_ON_ERROR);
+            assert(is_array($decoded));
+            return new $type($decoded['result']);
+        } catch (JsonException) {
+            $this->error();
+        } finally {
+            curl_close($ch);
+        }
+    }
+
+    /**
+     * TODO: specific error info!
+     */
+    private function error(): never
+    {
+        throw new ApiError();
+        // TODO: also make this more specific
+    }
+
+    public function __debugInfo(): array
+    {
+        return [
+            'apiHost' => $this->apiHost,
+            'secretKey' => substr($this->secretKey, 0, 9) . '***' . substr($this->secretKey, -2),
+        ];
+    }
+}

src/User.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SnapAuth;
+
+class User
+{
+    public readonly string $id;
+    public readonly string $handle;
+
+    // @phpstan-ignore-next-line
+    public function __construct(array $data)
+    {
+        $this->id = $data['id'];
+        $this->handle = $data['handle'];
+    }
+}