Updated extensions

Models that belong to an organization via a parent model (for example
project members via their project) implement AuditableThroughParent and
return the parent relation. The owner organization of their audits is
taken from the loaded parent if it matches the foreign key, otherwise it
is queried. The declaration is also used to backfill the owner of
existing audits.

app/Http/Controllers/Api/V1/InvitationController.php

@@ -88,6 +88,8 @@ class InvitationController extends Controller
     /**
      * Remove a pending invitation
      *
+     * This revokes the invitation: the link in the invitation email stops working. Find the invitation ID with `GET /organizations/{organization}/invitations`.
+     *
      * @throws AuthorizationException
      *
      * @operationId removeInvitation

app/Http/Controllers/Api/V1/MemberController.php

@@ -145,6 +145,9 @@ class MemberController extends Controller
     /**
      * Merge one member into another
      *
+     * Only placeholder members (for example people created by an import) can be merged. All time entries and other data of the placeholder
+     * are reassigned to the member given in `member_id`, and the placeholder is removed. Find both member IDs with `GET /organizations/{organization}/members`.
+     *
      * @throws AuthorizationException
      * @throws OnlyPlaceholdersCanBeMergedIntoAnotherMember
      * @throws Throwable

app/Http/Controllers/Api/V1/ReportController.php

@@ -71,6 +71,8 @@ class ReportController extends Controller
     /**
      * Create report
      *
+     * A report is a saved set of filters. Set `is_public` to `true` to share it: the response then contains the `shareable_link` that can be opened without logging in.
+     *
      * @throws AuthorizationException
      *
      * @operationId createReport

app/Http/Controllers/Api/V1/TimeEntryController.php

@@ -109,9 +109,14 @@ class TimeEntryController extends Controller
     /**
      * Get time entries in organization
      *
-     * If you only need time entries for a specific user, you can filter by `member_id`.
+     * Without a member filter this returns the time entries of all members of the organization (for users who may view all time entries, such as owners and admins), not only your own.
+     * To get only your own time entries, pass your member ID as `member_id`. Your member ID is the `id` returned for this organization by `GET /v1/users/me/memberships`; it is not your user ID.
      * Users with the permission `time-entries:view:own` can only use this endpoint with their own member ID in the member_id filter.
      *
+     * The `start` and `end` filters both apply to the start time of an entry, in UTC. Convert the user's local day boundaries to UTC first.
+     * Results are paginated with `limit` (default 100, max 500) and `offset`; check `meta.total` and fetch further pages when needed.
+     * To find the running timer, use `active=true` (or `GET /v1/users/me/time-entries/active`).
+     *
      * @return TimeEntryCollection<TimeEntryResource>
      *
      * @throws AuthorizationException
@@ -351,6 +356,11 @@ class TimeEntryController extends Controller
      * The parameters `group` and `sub_group` allow you to group the time entries by different criteria.
      * If the group parameters are all set to `null` or are all missing, the endpoint will aggregate all filtered time entries.
      *
+     * Durations are returned in `seconds` (divide by 3600 for hours) and amounts in `cost` as cents in the organization's currency (divide by 100 for money).
+     * Filter by member with `member_id`. Your member ID is the `id` returned for this organization by `GET /v1/users/me/memberships`; it is not your user ID.
+     * Array filters use the query format `client_ids[]=<id>`.
+     * Example: billable hours per client for a period: `group=client&billable=true&start=...&end=...`.
+     *
      * @operationId getAggregatedTimeEntries
      *
      * @return array{
@@ -584,6 +594,12 @@ class TimeEntryController extends Controller
     /**
      * Create time entry
      *
+     * `billable` is not taken from the project. To match the web app, set it to the project's `is_billable` value (or `false` without a project).
+     *
+     * A member can only have one running time entry (an entry with `end` set to `null`). Creating a running entry while another one runs fails with `time_entry_still_running`.
+     * To start a new timer, first stop the running entry by updating its `end` to the current time, then create the new entry.
+     * To log past work, send both `start` and `end` (UTC). Create one entry per block of work.
+     *
      * @throws AuthorizationException
      * @throws TimeEntryStillRunningApiException
      *
@@ -634,6 +650,8 @@ class TimeEntryController extends Controller
     /**
      * Update time entry
      *
+     * To stop a running timer, set `end` to the stop time (UTC). Times the user gives in their own timezone must be converted to UTC first.
+     *
      * @throws AuthorizationException|TimeEntryCanNotBeRestartedApiException
      *
      * @operationId updateTimeEntry
@@ -702,6 +720,10 @@ class TimeEntryController extends Controller
     /**
      * Update multiple time entries
      *
+     * Applies the same `changes` to every entry in `ids`. To find the IDs, list entries with `GET /organizations/{organization}/time-entries`
+     * (filtered by `member_id`, the project and the other criteria), then send their IDs here.
+     * When `changes.project_id` moves entries to another project, also set `changes.task_id` to a task of the new project or to `null`, because tasks belong to a project.
+     *
      * @operationId updateMultipleTimeEntries
      *
      * @throws AuthorizationException

app/Http/Requests/V1/Member/MemberUpdateRequest.php

@@ -27,6 +27,7 @@ class MemberUpdateRequest extends BaseFormRequest
                 'string',
                 Rule::enum(Role::class),
             ],
+            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/Organization/OrganizationUpdateRequest.php

@@ -36,6 +36,7 @@ class OrganizationUpdateRequest extends BaseFormRequest
                 'string',
                 new CurrencyRule,
             ],
+            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/Project/ProjectStoreRequest.php

@@ -55,6 +55,7 @@ class ProjectStoreRequest extends BaseFormRequest
                 'required',
                 'boolean',
             ],
+            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/Project/ProjectUpdateRequest.php

@@ -68,6 +68,7 @@ class ProjectUpdateRequest extends BaseFormRequest
                     return $builder->whereBelongsTo($this->organization, 'organization');
                 })->uuid(),
             ],
+            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge([
                 'nullable',
             ],

app/Http/Requests/V1/ProjectMember/ProjectMemberStoreRequest.php

@@ -31,6 +31,7 @@ class ProjectMemberStoreRequest extends BaseFormRequest
                     return $builder->whereBelongsTo($this->organization, 'organization');
                 })->uuid(),
             ],
+            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/ProjectMember/ProjectMemberUpdateRequest.php

@@ -21,6 +21,7 @@ class ProjectMemberUpdateRequest extends BaseFormRequest
     public function rules(): array
     {
         return [
+            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/TimeEntry/TimeEntryIndexRequest.php

@@ -35,7 +35,7 @@ class TimeEntryIndexRequest extends BaseFormRequest
     public function rules(): array
     {
         return [
-            // Filter by member ID
+            // Filter by member ID. Without it, users who may view all time entries (owners, admins) get the entries of every member; pass your own member ID (from GET /v1/users/me/memberships) to get only yours
             'member_id' => [
                 'string',
                 ExistsEloquent::make(Member::class, null, function (Builder $builder): Builder {
@@ -155,7 +155,7 @@ class TimeEntryIndexRequest extends BaseFormRequest
                 'string',
                 Rule::enum(TimeEntryType::class),
             ],
-            // Limit the number of returned time entries (default: 150)
+            // Limit the number of returned time entries (default: 100)
             'limit' => [
                 'integer',
                 'min:1',

app/Http/Requests/V1/TimeEntry/TimeEntryStoreRequest.php

@@ -32,7 +32,7 @@ class TimeEntryStoreRequest extends BaseFormRequest
     public function rules(): array
     {
         return [
-            // ID of the organization member that the time entry should belong to
+            // ID of the organization member that the time entry should belong to (a member ID from GET /v1/users/me/memberships or the members list, not a user ID)
             'member_id' => [
                 'required',
                 'string',
@@ -86,7 +86,7 @@ class TimeEntryStoreRequest extends BaseFormRequest
                 'date_format:Y-m-d\TH:i:s\Z',
                 'after_or_equal:start',
             ],
-            // Whether time entry is billable
+            // Whether time entry is billable. Not derived from the project: set it to the project's is_billable value to match the web app
             'billable' => [
                 'required',
                 'boolean',

app/Models/Audit.php

@@ -4,15 +4,19 @@ declare(strict_types=1);
 
 namespace App\Models;
 
+use App\Models\Concerns\AuditableWithoutOwner;
 use Database\Factories\AuditFactory;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\Relation;
 use Illuminate\Support\Carbon;
 use OwenIt\Auditing\Models\Audit as PackageAuditModel;
 
 /**
  * @property int $id
- * @property string|null $user_type
- * @property string|null $user_id
+ * @property string|null $actor_type
+ * @property string|null $actor_id
  * @property string $event
  * @property string $auditable_type
  * @property string $auditable_id
@@ -22,13 +26,71 @@ use OwenIt\Auditing\Models\Audit as PackageAuditModel;
  * @property string|null $ip_address
  * @property string|null $user_agent
  * @property string|null $tags
+ * @property string|null $owner_user_id
+ * @property string|null $owner_organization_id
  * @property Carbon|null $created_at
  * @property Carbon|null $updated_at
+ * @property-read User|null $ownerUser
+ * @property-read Organization|null $ownerOrganization
  *
  * @method static AuditFactory factory()
+ * @method static Builder<Audit> whereMissingOwner()
  */
 class Audit extends PackageAuditModel
 {
     /** @use HasFactory<AuditFactory> */
     use HasFactory;
+
+    /**
+     * @return BelongsTo<User, $this>
+     */
+    public function ownerUser(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'owner_user_id');
+    }
+
+    /**
+     * @return BelongsTo<Organization, $this>
+     */
+    public function ownerOrganization(): BelongsTo
+    {
+        return $this->belongsTo(Organization::class, 'owner_organization_id');
+    }
+
+    /**
+     * Whether audits of the given auditable type intentionally have no owner (see AuditableWithoutOwner).
+     */
+    public static function isAuditableTypeWithoutOwner(string $auditableType): bool
+    {
+        $modelClass = Relation::getMorphedModel($auditableType) ?? $auditableType;
+
+        return is_subclass_of($modelClass, AuditableWithoutOwner::class);
+    }
+
+    /**
+     * Auditable types (morph aliases) whose audits intentionally have no owner (see AuditableWithoutOwner).
+     *
+     * @return array<int, string>
+     */
+    public static function getAuditableTypesWithoutOwner(): array
+    {
+        return collect(Relation::morphMap())
+            ->filter(fn (string $modelClass): bool => is_subclass_of($modelClass, AuditableWithoutOwner::class))
+            ->keys()
+            ->values()
+            ->all();
+    }
+
+    /**
+     * Audits that have neither an owner organization nor an owner user, although their auditable type should have one.
+     * These are audits whose owner no longer exists or could not be determined (yet).
+     *
+     * @param  Builder<Audit>  $builder
+     */
+    public function scopeWhereMissingOwner(Builder $builder): void
+    {
+        $builder->whereNull('owner_organization_id')
+            ->whereNull('owner_user_id')
+            ->whereNotIn('auditable_type', self::getAuditableTypesWithoutOwner());
+    }
 }

app/Models/Concerns/AuditableThroughParent.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models\Concerns;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * Marks an auditable model whose audits are owned by the owner of its parent model,
+ * because the model itself has no organization_id (for example a project member belongs to an organization via its project).
+ * The parent model has to have an organization_id column.
+ * This is used to set the owner of new audits (CustomAuditable) and to backfill the owner of existing audits.
+ */
+interface AuditableThroughParent
+{
+    /**
+     * @return BelongsTo<covariant Model, covariant Model>
+     */
+    public function getAuditParentRelation(): BelongsTo;
+}

app/Models/Concerns/AuditableWithoutOwner.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models\Concerns;
+
+/**
+ * Marks an auditable model whose audits intentionally have no owner (neither an organization nor a user),
+ * either because the model belongs to neither of them, or because the model and its audits have to be kept
+ * when its organization or user is deleted (for example billing records).
+ * Audits of these models are not deleted together with an organization or user,
+ * and are not considered as missing an owner (for example by the audit backfill command).
+ */
+interface AuditableWithoutOwner {}

app/Models/Concerns/CustomAuditable.php

@@ -4,6 +4,8 @@ declare(strict_types=1);
 
 namespace App\Models\Concerns;
 
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Facades\Config;
 use OwenIt\Auditing\Auditable;
 
 trait CustomAuditable
@@ -19,4 +21,92 @@ trait CustomAuditable
     {
         $this->auditEvents = [];
     }
+
+    /**
+     * The organization that owns the audited model.
+     * The audits of the model are deleted (via foreign key cascade) when the organization is deleted.
+     */
+    public function getAuditOwnerOrganizationId(): ?string
+    {
+        if ($this instanceof AuditableThroughParent) {
+            $relation = $this->getAuditParentRelation();
+            $parentId = $this->getAttributes()[$relation->getForeignKeyName()] ?? null;
+            if ($parentId === null) {
+                return null;
+            }
+
+            // Note: The loaded parent is only used if it still matches the foreign key and was loaded with the organization
+            $relationName = $relation->getRelationName();
+            if ($this->relationLoaded($relationName)) {
+                $parent = $this->getRelation($relationName);
+                if ($parent instanceof Model
+                    && $parent->getAttribute($relation->getOwnerKeyName()) === $parentId
+                    && array_key_exists('organization_id', $parent->getAttributes())) {
+                    /** @var string|null $organizationId */
+                    $organizationId = $parent->getAttributes()['organization_id'];
+
+                    return $organizationId;
+                }
+            }
+
+            /** @var string|null $organizationId */
+            $organizationId = $relation->getRelated()->newQuery()
+                ->toBase()
+                ->where($relation->getOwnerKeyName(), $parentId)
+                ->value('organization_id');
+
+            return $organizationId;
+        }
+
+        return $this->getAttributes()['organization_id'] ?? null;
+    }
+
+    /**
+     * The user that owns the audited model.
+     * The audits of the model are deleted (via foreign key cascade) when the user is deleted.
+     */
+    public function getAuditOwnerUserId(): ?string
+    {
+        return null;
+    }
+
+    /**
+     * Models that are the owner of their own audits can not record the deletion audit,
+     * since the audit would reference the already deleted model and therefore violate the foreign key.
+     */
+    protected function isAuditOwnerOfItself(): bool
+    {
+        return false;
+    }
+
+    /**
+     * @return array<int|string, string>
+     */
+    public function getAuditEvents(): array
+    {
+        $events = $this->auditEvents ?? Config::get('audit.events', [
+            'created',
+            'updated',
+            'deleted',
+            'restored',
+        ]);
+
+        if ($this->isAuditOwnerOfItself()) {
+            $events = array_filter($events, fn (string $value, int|string $key): bool => (is_int($key) ? $value : $key) !== 'deleted', ARRAY_FILTER_USE_BOTH);
+        }
+
+        return $events;
+    }
+
+    /**
+     * @param  array<string, mixed>  $data
+     * @return array<string, mixed>
+     */
+    public function transformAudit(array $data): array
+    {
+        $data['owner_organization_id'] = $this->getAuditOwnerOrganizationId();
+        $data['owner_user_id'] = $this->getAuditOwnerUserId();
+
+        return $data;
+    }
 }

app/Models/Organization.php

@@ -96,6 +96,16 @@ class Organization extends Model implements AuditableContract
     protected $attributes = [
     ];
 
+    public function getAuditOwnerOrganizationId(): ?string
+    {
+        return $this->getKey();
+    }
+
+    protected function isAuditOwnerOfItself(): bool
+    {
+        return true;
+    }
+
     /**
      * Get all the users that belong to the team.
      *

app/Models/ProjectMember.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Models;
 
+use App\Models\Concerns\AuditableThroughParent;
 use App\Models\Concerns\CustomAuditable;
 use App\Models\Concerns\HasUuids;
 use Database\Factories\ProjectMemberFactory;
@@ -29,7 +30,7 @@ use OwenIt\Auditing\Contracts\Auditable as AuditableContract;
  * @method static Builder<ProjectMember> whereBelongsToOrganization(Organization $organization)
  * @method static ProjectMemberFactory factory()
  */
-class ProjectMember extends Model implements AuditableContract
+class ProjectMember extends Model implements AuditableContract, AuditableThroughParent
 {
     use CustomAuditable;
 
@@ -82,4 +83,12 @@ class ProjectMember extends Model implements AuditableContract
             $query->whereBelongsTo($organization, 'organization');
         });
     }
+
+    /**
+     * @return BelongsTo<Project, $this>
+     */
+    public function getAuditParentRelation(): BelongsTo
+    {
+        return $this->project();
+    }
 }

app/Models/User.php

@@ -124,6 +124,16 @@ class User extends Authenticatable implements AuditableContract, FilamentUser, M
         'send_time_entry_still_running_email' => true,
     ];
 
+    public function getAuditOwnerUserId(): ?string
+    {
+        return $this->getKey();
+    }
+
+    protected function isAuditOwnerOfItself(): bool
+    {
+        return true;
+    }
+
     /**
      * Get the URL to the user's profile photo.
      *

config/audit.php

@@ -32,7 +32,7 @@ return [
     */
 
     'user' => [
-        'morph_prefix' => 'user',
+        'morph_prefix' => 'actor',
         'guards' => [
             'web',
             'api',

config/database.php

@@ -35,7 +35,7 @@ return [
 
         'sqlite' => [
             'driver' => 'sqlite',
-            'url' => env('DB_URL'),
+            'url' => env('DB_URL', env('DATABASE_URL')),
             'database' => env('DB_DATABASE', database_path('database.sqlite')),
             'prefix' => '',
             'foreign_key_constraints' => env('DB_FOREIGN_KEYS', true),
@@ -47,7 +47,7 @@ return [
 
         'pgsql' => [
             'driver' => 'pgsql',
-            'url' => env('DB_URL'),
+            'url' => env('DB_URL', env('DATABASE_URL')),
             'host' => env('DB_HOST', '127.0.0.1'),
             'port' => env('DB_PORT', '5432'),
             'database' => env('DB_DATABASE', 'forge'),
@@ -57,12 +57,12 @@ return [
             'prefix' => '',
             'prefix_indexes' => true,
             'search_path' => 'public',
-            'sslmode' => env('DB_SSLMODE', 'prefer'),
+            'sslmode' => env('DB_SSL_MODE', 'prefer'),
         ],
 
         'pgsql_test' => [
             'driver' => 'pgsql',
-            'url' => env('DB_URL'),
+            'url' => env('DB_URL', env('DATABASE_URL')),
             'host' => env('DB_TEST_HOST', '127.0.0.1'),
             'port' => env('DB_TEST_PORT', '5432'),
             'database' => env('DB_TEST_DATABASE', 'forge'),
@@ -72,12 +72,12 @@ return [
             'prefix' => '',
             'prefix_indexes' => true,
             'search_path' => 'public',
-            'sslmode' => env('DB_SSLMODE', 'prefer'),
+            'sslmode' => env('DB_SSL_MODE', 'prefer'),
         ],
 
         'sqlsrv' => [
             'driver' => 'sqlsrv',
-            'url' => env('DB_URL'),
+            'url' => env('DB_URL', env('DATABASE_URL')),
             'host' => env('DB_HOST', 'localhost'),
             'port' => env('DB_PORT', '1433'),
             'database' => env('DB_DATABASE', 'laravel'),

config/scramble.php

@@ -28,7 +28,30 @@ return [
         /*
          * Description rendered on the home page of the API documentation (`/docs/api`).
          */
-        'description' => '',
+        'description' => <<<'MD'
+## Getting started
+
+All organization endpoints live under `/v1/organizations/{organization}`, where `{organization}` is the organization's ID. Authenticate with `Authorization: Bearer <token>` and send `Accept: application/json`.
+
+**1. Find yourself.** Call `GET /v1/users/me/memberships`. Each membership contains the **organization ID** (use it as `{organization}` in paths) and your **member ID** in that organization (the membership `id`). Most endpoints filter by member ID, not by user ID.
+
+**2. Scope to your own data.** For owners and admins, `GET /time-entries` and `GET /time-entries/aggregate` return the whole organization's time entries unless you pass `member_id`. When acting for "me", always pass your member ID, both when reading and before changing entries.
+
+**3. Resolve names to IDs.** Look up projects, clients, tags, tasks and members by name with their list endpoints (`GET /projects`, `GET /clients`, `GET /tags`, `GET /tasks`, `GET /members`). Never guess IDs.
+
+**4. Use UTC.** All timestamps are sent and returned in UTC as `Y-m-d\TH:i:s\Z` (example: `2026-10-02T07:30:00Z`). Convert the user's local times and day boundaries to UTC before sending them.
+
+**5. Money is in cents.** Billable rates and costs are integers in cents of the organization's currency (`8000` means 80.00).
+
+## Common tasks
+
+- **Start a timer:** stop the running entry first (find it with `GET /v1/users/me/time-entries/active`, then `PUT` its `end`), then `POST /time-entries` with `start` and `end: null`. Only one entry can run per member.
+- **Log past work:** `POST /time-entries` once per block with `member_id`, `start`, `end`, `project_id` and `billable` set to the project's `is_billable` (it is not derived automatically).
+- **Fix or stop an entry:** `PUT /time-entries/{timeEntry}` with the new `start` or `end` in UTC.
+- **Move entries to another project:** list them with `member_id` and filters, then `PATCH /time-entries` with their `ids` and `changes.project_id`, plus `changes.task_id` set to a task of the new project or `null`.
+- **Totals and reports:** `GET /time-entries/aggregate` with `group` (for example `client` or `project`) and `start`/`end`; durations are in `seconds`, amounts in `cost` (cents).
+- **Share a report:** `POST /reports` with `is_public: true` and use the returned `shareable_link`.
+MD,
     ],
 
     /*

database/factories/UserFactory.php

@@ -91,7 +91,7 @@ class UserFactory extends Factory
 
     public function withProfilePicture(): static
     {
-        $profilePhoto = $this->faker->image(null, 500, 500);
+        $profilePhoto = $this->generateProfilePhoto();
         /** @see FileHelpers::hashName */
         $path = 'profile-photos/'.Str::random(40).'.png';
         Storage::disk(config('filesystems.public'))->put($path, $profilePhoto);
@@ -103,6 +103,21 @@ class UserFactory extends Factory
         });
     }
 
+    /**
+     * Generates a PNG image with a random background color.
+     * Note: The image is generated locally, since downloading a placeholder image (Faker image()) depends on an external service.
+     */
+    private function generateProfilePhoto(): string
+    {
+        $image = imagecreatetruecolor(500, 500);
+        $color = imagecolorallocate($image, $this->faker->numberBetween(0, 255), $this->faker->numberBetween(0, 255), $this->faker->numberBetween(0, 255));
+        imagefill($image, 0, 0, $color);
+        ob_start();
+        imagepng($image);
+
+        return (string) ob_get_clean();
+    }
+
     /**
      * Indicate that the user should have a personal team.
      */

database/migrations/2024_09_02_094105_create_audits_table.php

@@ -18,7 +18,8 @@ class CreateAuditsTable extends Migration
 
         Schema::connection($connection)->create($table, function (Blueprint $table): void {
 
-            $morphPrefix = config('audit.user.morph_prefix', 'user');
+            // Note: The morph prefix is hardcoded, since the columns are renamed in a later migration
+            $morphPrefix = 'user';
 
             $table->bigIncrements('id');
             $table->string($morphPrefix.'_type')->nullable();

database/migrations/2026_10_06_000001_add_owner_columns_to_audits_table.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     *
+     * Note: Renaming columns and adding nullable columns without default are metadata-only operations in PostgreSQL,
+     * so this migration is fast even for a large audits table.
+     * The indexes and foreign keys for the new columns are added in a separate non-transactional migration.
+     */
+    public function up(): void
+    {
+        Schema::table('audits', function (Blueprint $table): void {
+            $table->renameColumn('user_type', 'actor_type');
+            $table->renameColumn('user_id', 'actor_id');
+            $table->renameIndex('audits_user_id_user_type_index', 'audits_actor_id_actor_type_index');
+            $table->uuid('owner_user_id')->nullable();
+            $table->uuid('owner_organization_id')->nullable();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('audits', function (Blueprint $table): void {
+            $table->dropColumn('owner_user_id');
+            $table->dropColumn('owner_organization_id');
+            $table->renameIndex('audits_actor_id_actor_type_index', 'audits_user_id_user_type_index');
+            $table->renameColumn('actor_type', 'user_type');
+            $table->renameColumn('actor_id', 'user_id');
+        });
+    }
+};

database/migrations/2026_10_06_000002_add_owner_foreign_keys_to_audits_table.php

@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+return new class extends Migration
+{
+    /**
+     * PostgreSQL cannot build an index concurrently inside a transaction.
+     * Keeping this migration non-transactional prevents long write locks on the (large) audits table in production.
+     * Every step is idempotent, so the migration can be re-run if it fails halfway.
+     *
+     * @var bool
+     */
+    public $withinTransaction = false;
+
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        $this->createIndex('audits_owner_user_id_index', 'owner_user_id');
+        $this->createIndex('audits_owner_organization_id_index', 'owner_organization_id');
+
+        $this->createForeignKey('audits_owner_user_id_foreign', 'owner_user_id', 'users');
+        $this->createForeignKey('audits_owner_organization_id_foreign', 'owner_organization_id', 'organizations');
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        DB::statement('ALTER TABLE audits DROP CONSTRAINT IF EXISTS audits_owner_user_id_foreign');
+        DB::statement('ALTER TABLE audits DROP CONSTRAINT IF EXISTS audits_owner_organization_id_foreign');
+        DB::statement('DROP INDEX'.$this->concurrently().' IF EXISTS audits_owner_user_id_index');
+        DB::statement('DROP INDEX'.$this->concurrently().' IF EXISTS audits_owner_organization_id_index');
+    }
+
+    private function createIndex(string $index, string $column): void
+    {
+        $state = DB::selectOne(
+            <<<'SQL'
+                SELECT pg_index.indisvalid::int AS valid
+                FROM pg_index
+                JOIN pg_class ON pg_class.oid = pg_index.indexrelid
+                JOIN pg_namespace ON pg_namespace.oid = pg_class.relnamespace
+                WHERE pg_namespace.nspname = current_schema()
+                  AND pg_class.relname = ?
+                SQL,
+            [$index],
+        );
+
+        if ($state !== null && (bool) $state->valid) {
+            return;
+        }
+
+        // A failed concurrent index build leaves an invalid index behind, that needs to be dropped before rebuilding
+        if ($state !== null) {
+            DB::statement('DROP INDEX'.$this->concurrently().' '.$index);
+        }
+
+        DB::statement('CREATE INDEX'.$this->concurrently().' '.$index.' ON audits ('.$column.')');
+    }
+
+    private function createForeignKey(string $constraint, string $column, string $referencedTable): void
+    {
+        $exists = DB::selectOne(
+            <<<'SQL'
+                SELECT 1
+                FROM pg_constraint
+                JOIN pg_namespace ON pg_namespace.oid = pg_constraint.connamespace
+                WHERE pg_namespace.nspname = current_schema()
+                  AND pg_constraint.conname = ?
+                SQL,
+            [$constraint],
+        ) !== null;
+
+        // Note: Adding the constraint as NOT VALID only needs a short lock, the validation of the existing rows
+        // afterward does not block reads or writes on the audits table.
+        if (! $exists) {
+            DB::statement('ALTER TABLE audits ADD CONSTRAINT '.$constraint.' FOREIGN KEY ('.$column.') REFERENCES '.$referencedTable.' (id) ON DELETE CASCADE NOT VALID');
+        }
+
+        DB::statement('ALTER TABLE audits VALIDATE CONSTRAINT '.$constraint);
+    }
+
+    private function concurrently(): string
+    {
+        return DB::transactionLevel() === 0 ? ' CONCURRENTLY' : '';
+    }
+};

extensions/manifest.json

@@ -1,18 +1,18 @@
 {
     "Billing": {
         "repository": "solidtime-io/extension-billing",
-        "ref": "v0.0.8"
+        "ref": "v0.0.9"
     },
     "Services": {
         "repository": "solidtime-io/extension-services",
-        "ref": "v0.0.3"
+        "ref": "v0.0.4"
     },
     "Invoicing": {
         "repository": "solidtime-io/extension-invoicing",
-        "ref": "v0.0.7"
+        "ref": "v0.0.8"
     },
     "Auditing": {
         "repository": "solidtime-io/extension-auditing",
-        "ref": "v0.0.2"
+        "ref": "v0.0.4"
     }
 }

tests/Unit/Middleware/TrustHostsTest.php

@@ -50,7 +50,8 @@ class TrustHostsTest extends TestCase
         $this->middleware()->handle($request, fn (Request $request): Response => new Response('passed'));
 
         try {
-            dump($request->getHost());
+            // Note: Throws an exception if the host is not trusted
+            $request->getHost();
 
             return true;
         } catch (\Throwable) {

tests/Unit/Model/AuditModelTest.php

@@ -0,0 +1,209 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Model;
+
+use App\Models\Audit;
+use App\Models\Concerns\AuditableWithoutOwner;
+use App\Models\Member;
+use App\Models\Organization;
+use App\Models\Project;
+use App\Models\ProjectMember;
+use App\Models\TimeEntry;
+use App\Models\User;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\Relation;
+use Illuminate\Support\Facades\DB;
+use PHPUnit\Framework\Attributes\CoversClass;
+
+#[CoversClass(Audit::class)]
+class AuditModelTest extends ModelTestAbstract
+{
+    public function test_it_belongs_to_an_owner_organization(): void
+    {
+        // Arrange
+        $organization = Organization::factory()->create();
+        $audit = Audit::factory()->create([
+            'owner_organization_id' => $organization->getKey(),
+        ]);
+
+        // Act
+        $audit->refresh();
+        $ownerOrganizationRel = $audit->ownerOrganization;
+
+        // Assert
+        $this->assertNotNull($ownerOrganizationRel);
+        $this->assertTrue($ownerOrganizationRel->is($organization));
+    }
+
+    public function test_it_belongs_to_an_owner_user(): void
+    {
+        // Arrange
+        $user = User::factory()->create();
+        $audit = Audit::factory()->create([
+            'owner_user_id' => $user->getKey(),
+        ]);
+
+        // Act
+        $audit->refresh();
+        $ownerUserRel = $audit->ownerUser;
+
+        // Assert
+        $this->assertNotNull($ownerUserRel);
+        $this->assertTrue($ownerUserRel->is($user));
+    }
+
+    public function test_audits_of_models_with_organization_have_the_organization_as_owner(): void
+    {
+        // Arrange
+        $organization = Organization::factory()->create();
+        $member = Member::factory()->forOrganization($organization)->create();
+
+        // Act
+        $timeEntry = TimeEntry::factory()->forOrganization($organization)->forMember($member)->create();
+
+        // Assert
+        $audit = Audit::query()->where('auditable_id', $timeEntry->getKey())->sole();
+        $this->assertSame($organization->getKey(), $audit->owner_organization_id);
+        $this->assertNull($audit->owner_user_id);
+    }
+
+    public function test_audits_of_project_members_have_the_organization_of_the_project_as_owner(): void
+    {
+        // Arrange
+        $organization = Organization::factory()->create();
+        $project = Project::factory()->forOrganization($organization)->create();
+        $member = Member::factory()->forOrganization($organization)->create();
+
+        // Act
+        $projectMember = ProjectMember::factory()->forProject($project)->forMember($member)->create();
+
+        // Assert
+        $audit = Audit::query()->where('auditable_id', $projectMember->getKey())->sole();
+        $this->assertSame($organization->getKey(), $audit->owner_organization_id);
+        $this->assertNull($audit->owner_user_id);
+    }
+
+    public function test_owner_organization_through_parent_uses_the_loaded_parent_without_query(): void
+    {
+        // Arrange
+        $organization = Organization::factory()->create();
+        $project = Project::factory()->forOrganization($organization)->create();
+        $projectMember = ProjectMember::factory()->forProject($project)->forMember(Member::factory()->forOrganization($organization)->create())->create();
+        $projectMember->load('project');
+        DB::enableQueryLog();
+
+        // Act
+        $ownerOrganizationId = $projectMember->getAuditOwnerOrganizationId();
+
+        // Assert
+        $this->assertSame($organization->getKey(), $ownerOrganizationId);
+        $this->assertCount(0, DB::getQueryLog());
+    }
+
+    public function test_owner_organization_through_parent_ignores_a_loaded_parent_that_does_not_match_the_foreign_key(): void
+    {
+        // Arrange
+        $organization = Organization::factory()->create();
+        $otherOrganization = Organization::factory()->create();
+        $project = Project::factory()->forOrganization($organization)->create();
+        $otherProject = Project::factory()->forOrganization($otherOrganization)->create();
+        $projectMember = ProjectMember::factory()->forProject($project)->forMember(Member::factory()->forOrganization($organization)->create())->create();
+        $projectMember->load('project');
+        $projectMember->project_id = $otherProject->getKey();
+
+        // Act
+        $ownerOrganizationId = $projectMember->getAuditOwnerOrganizationId();
+
+        // Assert
+        $this->assertSame($otherOrganization->getKey(), $ownerOrganizationId);
+    }
+
+    public function test_audits_of_an_organization_have_the_organization_itself_as_owner(): void
+    {
+        // Act
+        $organization = Organization::factory()->create();
+
+        // Assert
+        $audit = Audit::query()->where('auditable_id', $organization->getKey())->sole();
+        $this->assertSame($organization->getKey(), $audit->owner_organization_id);
+        $this->assertNull($audit->owner_user_id);
+    }
+
+    public function test_audits_of_a_user_have_the_user_itself_as_owner(): void
+    {
+        // Act
+        $user = User::factory()->create();
+
+        // Assert
+        $audit = Audit::query()->where('auditable_id', $user->getKey())->sole();
+        $this->assertSame($user->getKey(), $audit->owner_user_id);
+        $this->assertNull($audit->owner_organization_id);
+    }
+
+    public function test_deleting_an_owner_deletes_its_audits_and_does_not_create_a_deletion_audit(): void
+    {
+        // Arrange
+        $user = User::factory()->create();
+        $organization = Organization::factory()->create();
+        $otherUser = User::factory()->create();
+
+        // Act
+        $user->delete();
+        $organization->delete();
+
+        // Assert
+        $this->assertSame(0, Audit::query()->where('auditable_id', $user->getKey())->count());
+        $this->assertSame(0, Audit::query()->where('auditable_id', $organization->getKey())->count());
+        $this->assertSame(1, Audit::query()->where('auditable_id', $otherUser->getKey())->count());
+    }
+
+    public function test_auditable_types_without_owner_are_determined_by_the_marker_interface(): void
+    {
+        // Arrange
+        $originalMorphMap = Relation::morphMap();
+        $modelWithoutOwner = new class extends Model implements AuditableWithoutOwner {};
+        Relation::morphMap(['model-without-owner' => $modelWithoutOwner::class]);
+
+        try {
+            // Act
+            $typesWithoutOwner = Audit::getAuditableTypesWithoutOwner();
+            $isWithoutOwner = Audit::isAuditableTypeWithoutOwner('model-without-owner');
+            $isTimeEntryWithoutOwner = Audit::isAuditableTypeWithoutOwner((new TimeEntry)->getMorphClass());
+
+            // Assert
+            $this->assertContains('model-without-owner', $typesWithoutOwner);
+            $this->assertNotContains((new TimeEntry)->getMorphClass(), $typesWithoutOwner);
+            $this->assertTrue($isWithoutOwner);
+            $this->assertFalse($isTimeEntryWithoutOwner);
+        } finally {
+            Relation::morphMap($originalMorphMap, false);
+        }
+    }
+
+    public function test_scope_where_missing_owner_only_returns_audits_without_owner_whose_type_should_have_one(): void
+    {
+        // Arrange
+        $originalMorphMap = Relation::morphMap();
+        $modelWithoutOwner = new class extends Model implements AuditableWithoutOwner {};
+        Relation::morphMap(['model-without-owner' => $modelWithoutOwner::class]);
+        $organization = Organization::factory()->create();
+        $user = User::factory()->create();
+        Audit::query()->delete();
+        $missingOwnerAudit = Audit::factory()->create(['auditable_type' => (new TimeEntry)->getMorphClass()]);
+        Audit::factory()->create(['auditable_type' => (new TimeEntry)->getMorphClass(), 'owner_organization_id' => $organization->getKey()]);
+        Audit::factory()->create(['owner_user_id' => $user->getKey()]);
+        Audit::factory()->create(['auditable_type' => 'model-without-owner']);
+
+        try {
+            // Act
+            $auditIds = Audit::query()->whereMissingOwner()->pluck('id')->all();
+
+            // Assert
+            $this->assertSame([$missingOwnerAudit->getKey()], $auditIds);
+        } finally {
+            Relation::morphMap($originalMorphMap, false);
+        }
+    }
+}

tests/Unit/Service/DeletionServiceTest.php

@@ -7,6 +7,7 @@ namespace Tests\Unit\Service;
 use App\Enums\Role;
 use App\Events\BeforeOrganizationDeletion;
 use App\Exceptions\Api\CanNotDeleteUserWhoIsOwnerOfOrganizationWithMultipleMembers;
+use App\Models\Audit;
 use App\Models\Client;
 use App\Models\Member;
 use App\Models\Organization;
@@ -182,6 +183,8 @@ class DeletionServiceTest extends TestCaseWithDatabase
         // Assert
         $this->assertOrganizationDeleted($organization->organization);
         $this->assertOrganizationNothingDeleted($otherOrganization->organization);
+        $this->assertSame(0, Audit::query()->where('owner_organization_id', $organization->organization->getKey())->count());
+        $this->assertGreaterThan(0, Audit::query()->where('owner_organization_id', $otherOrganization->organization->getKey())->count());
         Log::assertLoggedTimes(fn (LogEntry $log) => $log->level === 'debug'
             && $log->message === 'Start deleting organization'
             && $log->context['organization_id'] === $organization->organization->getKey(),
@@ -318,6 +321,10 @@ class DeletionServiceTest extends TestCaseWithDatabase
         $this->assertDatabaseMissing(Member::class, [
             'user_id' => $user->getKey(),
         ]);
+        $this->assertSame(0, Audit::query()->where('owner_user_id', $user->getKey())->count());
+        $this->assertSame(0, Audit::query()->where('owner_organization_id', $user->current_team_id)->count());
+        $this->assertGreaterThan(0, Audit::query()->where('owner_user_id', $otherUser->getKey())->count());
+        $this->assertGreaterThan(0, Audit::query()->where('owner_organization_id', $otherUser->current_team_id)->count());
         Storage::disk(config('filesystems.public'))->assertMissing($user->profile_photo_path);
         Storage::disk(config('filesystems.public'))->assertExists($otherUser->profile_photo_path);
         Log::assertLoggedTimes(fn (LogEntry $log) => $log->level === 'debug'
@@ -332,6 +339,24 @@ class DeletionServiceTest extends TestCaseWithDatabase
         );
     }
 
+    public function test_delete_user_keeps_audits_of_other_organizations_where_the_user_is_the_actor(): void
+    {
+        // Arrange
+        $user = User::factory()->withPersonalOrganization()->create();
+        $otherOrganization = Organization::factory()->create();
+        $audit = Audit::factory()->auditUser($user)->auditFor($otherOrganization)->create([
+            'owner_organization_id' => $otherOrganization->getKey(),
+        ]);
+
+        // Act
+        $this->deletionService->deleteUser($user);
+
+        // Assert
+        $audit->refresh();
+        $this->assertSame($user->getKey(), $audit->actor_id);
+        $this->assertSame($otherOrganization->getKey(), $audit->owner_organization_id);
+    }
+
     public function test_delete_user_deletes_owned_organizations_that_have_only_one_member_and_makes_makes_the_user_placeholder_in_not_owned_organizations(): void
     {
         // Arrange