Stemplin time tracking

Stemplin is a time tracking application written in Ruby on Rails.

Self hosting

See the self hosing guide here: https://github.com/rubynor/stemplin/blob/main/SELF_HOSTING.md

REST API

Stemplin provides a REST API under /api/v1/ with Bearer token authentication.

Authentication

Generate an API token via the Rails console:

user = User.find_by(email: "[email protected]")
token = user.regenerate_api_token!
puts token # save this — it's only shown once

Use the token in requests:

curl -H "Authorization: Bearer <token>" \
     -H "X-Organization-Id: <org_id>" \
     https://your-host/api/v1/users/me

The X-Organization-Id header is optional — if omitted, the user's default organization is used.

Endpoints

Time registrations support filtering with ?date=, ?start_date=&end_date=, and ?project_id= query params, plus pagination with ?page=&per_page=.

Token security

API tokens are hashed with SHA-256 before storage. The plaintext token is only returned once at creation/regeneration time. Treat it like a password.

Contributing

See the contribution guidelines in:

https://github.com/rubynor/stemplin/blob/main/CONTRIBUTING.md

Setting Up Locally

Installing the project

Install the project's dependencies by running:

cp .env.sample .env
bin/setup
yarn install

Populate the database from fixtures:

rails db:fixtures:load

Redis

Hotwire will not work without Redis. If it is not running, start it with:

redis-server --daemonize yes

Run the project

Finally, you can run your project locally with:

bin/dev

Open your browser and visit http://localhost:3000, your project should be running!

Lint

Run linter with:

bin/rubocop

Or run autocorrection with:

bin/rubocop -a

Authorization

This project uses ActionPolicy for authorization.

Rules

1. ALWAYS use authorized_scope when querying the database, to prevent data leakage.

2. Use authorize! in EVERY SINGLE controller action, and create a policy for EVERY SINGLE controller action.

Action Policy concepts

Policies

Policies are used to limit a current_user's access to controller methods. Policies are defined like so:

• user holds the value of current_user

• record holds the value of whatever is passed in to the authorize! method. If nothing is passed, record will hold the model class, that is based on the controller name. In this case that class is Client

  
  # app/policies/time_reg_policy.rb

class TimeRegPolicy < ApplicationPolicy def index?

Allows all users to access the index action

true

end end

```ruby
# app/policies/client_policy.rb

class ClientPolicy < ApplicationPolicy
  def index?
    # As the index action fetches an entire collection, `record` is not relevant
    # This allows organization_admins to access the action
    user.organization_admin?
  end

  def create?
    # Allows organization_admins in the Client's organization access to the action
    user.organization_admin? && user.current_organization == record.oragnization
  end
end

Scopes

Scopes are used to scope out records that the current_user can access in a collection. Define a scope like so:

# app/policies/time_reg_policy.rb

class TimeRegPolicy < ApplicationPolicy
  scope_for :relation, :own do |relation|
    # Scopes out the user's own TimeRegs
    relation.joins(:organization, :user).where(organizations: user.current_organization, user: user).distinct
  end
end

# app/policies/client_policy.rb

class ClientPolicy < ApplicationPolicy
  scope_for :relation do |relation|
    # Scopes out Clients accessible for organization_admin
    if user.organization_admin?
      relation.joins(:organization).where(organizations: user.current_organization).distinct
    else
      relation.none
    end
  end
end

Example usage of policies and scopes

# app/controllers/clients_controller.rb

class ClientsController < ApplicationController
  def index
    # Where the controller fetches an entire collection, 
    # use the `authorize!` method without passing in a record (implicitly)
    authorize!
    @clients = authorized_scope(Client, type: :relation).all
  end

  def show
    @client = authorized_scope(Client, type: :relation).find(params[:id])
    # Where the controller fetches a single record,
    # use the `authorize!` method passing in a record (explicitly)
    authorize! @client
  end

  def create
    # Use `authorized_scope` when initializing a record
    @client = authorized_scope(Client, type: :relation).new(client_params)
    # Use `authorize!` before saving a record
    authorize! @clinet

    @client.save!
  end
end