Security

// Keys are the verification keys, by key id. The key, not the token header, decides the
// algorithm, so a token cannot switch to "none" or to HS256 signed with a public key.
type Keys struct {
  HMAC     map[string][]byte
  Ed25519  map[string]ed25519.PublicKey
  Issuer   string
  Audience string
}

// Verify checks a token's signature, algorithm, time window, issuer and audience, and returns
// its claims. Revocation is a separate check, because it needs a store.
func (k Keys) Verify(token string, now time.Time) (Claims, error) {
  parts := strings.Split(token, ".")
  if len(parts) != 3 {
    return Claims{}, ErrMalformed
  }
  var h header
  if err := decode(parts[0], &h); err != nil {
    return Claims{}, err
  }
  signed := []byte(parts[0] + "." + parts[1])
  sig, err := b64.DecodeString(parts[2])
  if err != nil {
    return Claims{}, ErrMalformed
  }
  switch {
  case k.HMAC[h.Kid] != nil:
    if h.Alg != "HS256" {
      return Claims{}, ErrAlg
    }
    m := hmac.New(sha256.New, k.HMAC[h.Kid])
    m.Write(signed)
    if !hmac.Equal(sig, m.Sum(nil)) { // constant time
      return Claims{}, ErrSignature
    }
  case k.Ed25519[h.Kid] != nil:
    if h.Alg != "EdDSA" {
      return Claims{}, ErrAlg
    }
    if !ed25519.Verify(k.Ed25519[h.Kid], signed, sig) {
      return Claims{}, ErrSignature
    }
  default:
    return Claims{}, ErrUnknownKey
  }
  var c Claims
  if err := decode(parts[1], &c); err != nil {
    return Claims{}, err
  }
  switch {
  case now.Unix() >= c.Exp:
    return Claims{}, ErrExpired
  case c.Iat > now.Unix()+30: // 30 s of clock skew
    return Claims{}, ErrNotYet
  case c.Iss != k.Issuer || c.Aud != k.Audience:
    return Claims{}, ErrAudience
  }
  return c, nil
}

// Revocations is a deny-list of token ids in Redis. An entry lives only until the token would
// expire anyway, so the list stays as small as the tokens revoked in one token lifetime.
type Revocations struct{ R *redis.Client }

// Revoke denies the token with id jti for ttl, the time the token has left.
func (v Revocations) Revoke(ctx context.Context, jti string, ttl time.Duration) error {
  if err := v.R.Set(ctx, "revoked:"+jti, 1, ttl).Err(); err != nil {
    return fmt.Errorf("revoke %s: %w", jti, err)
  }
  return nil
}

// Revoked reports whether jti is on the deny-list. Every request pays this one lookup.
func (v Revocations) Revoked(ctx context.Context, jti string) (bool, error) {
  n, err := v.R.Exists(ctx, "revoked:"+jti).Result()
  if err != nil {
    return false, fmt.Errorf("check revocation of %s: %w", jti, err)
  }
  return n == 1, nil
}

// Handle runs every check in order and stops at the first that fails.
func (s *Service) Handle(ctx context.Context, req Request) (Decision, error) {
  var d Decision
  // 1. Authentication: who is calling? A bad token is 401.
  c, err := s.Keys.Verify(req.Token, s.Now())
  if err == nil {
    var revoked bool
    if revoked, err = s.Revoked.Revoked(ctx, c.Jti); err != nil {
      return d, err
    }
    if revoked {
      err = ErrRevoked
    }
  }
  if err != nil {
    d.add("token", "fail", err.Error())
    d.Status = http.StatusUnauthorized
    return d, nil
  }
  d.add("token", "pass", fmt.Sprintf("user %d, tenant %d, role %s", c.Sub, c.Tenant, c.Role))

  // 2. Function level: may this role take this action at all? No is 403.
  if !slices.Contains(Permissions[c.Role], req.Action) {
    d.add("role", "fail", fmt.Sprintf("role %s may not %s", c.Role, req.Action))
    d.Status = http.StatusForbidden
    return d, nil
  }
  d.add("role", "pass", fmt.Sprintf("role %s may %s", c.Role, req.Action))

  if s.MissingObjectCheck {
    return s.handleWithoutObjectCheck(ctx, c, req, d)
  }

  // 3 and 4 run in one transaction, as the service role, with the caller's tenant set.
  err = pgx.BeginFunc(ctx, s.DB, func(tx pgx.Tx) error {
    if _, err := tx.Exec(ctx, schema["as_tenant"], strconv.FormatInt(c.Tenant, 10)); err != nil {
      return fmt.Errorf("set tenant: %w", err)
    }
    // 3. Tenant: row-level security returns only this tenant's rows. Not found is 404,
    // so a caller cannot learn that another tenant's document exists.
    var tenant, owner int64
    var title string
    err := tx.QueryRow(ctx, schema["load"], req.Doc).Scan(&tenant, &owner, &title)
    if errors.Is(err, pgx.ErrNoRows) {
      d.add("tenant", "fail", fmt.Sprintf("row-level security shows no document %d in tenant %d", req.Doc, c.Tenant))
      d.Status = http.StatusNotFound
      return s.audit(ctx, tx, c, req, d.Status)
    }
    if err != nil {
      return fmt.Errorf("load document %d: %w", req.Doc, err)
    }
    d.add("tenant", "pass", fmt.Sprintf("document %d is in tenant %d", req.Doc, tenant))

    // 4. Object level: a member edits only documents that member owns.
    if req.Action == "edit" && c.Role != "admin" && owner != c.Sub {
      d.add("owner", "fail", fmt.Sprintf("user %d owns document %d, not user %d", owner, req.Doc, c.Sub))
      d.Status = http.StatusForbidden
      return s.audit(ctx, tx, c, req, d.Status)
    }
    d.add("owner", "pass", ownerDetail(req.Action, c, owner))

    if d.Title, err = act(ctx, tx, req, title); err != nil {
      return err
    }
    d.Status = http.StatusOK
    return s.audit(ctx, tx, c, req, d.Status)
  })
  return d, err
}

// Argon2id parameters for stored passwords: 19 MiB, 2 passes, 1 lane (the OWASP minimum).
const (
  argonMemKiB = 19 * 1024
  argonTime   = 2
  argonLanes  = 1
)

// HashPassword returns a self-describing string: algorithm, version, parameters, salt, hash.
// The parameters travel with the hash, so a later login can verify old hashes and rehash them.
func HashPassword(pw string) (string, error) {
  salt := make([]byte, 16)
  if _, err := rand.Read(salt); err != nil {
    return "", fmt.Errorf("salt: %w", err)
  }
  key := argon2.IDKey([]byte(pw), salt, argonTime, argonMemKiB, argonLanes, 32)
  enc := base64.RawStdEncoding
  return fmt.Sprintf("$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s",
    argon2.Version, argonMemKiB, argonTime, argonLanes, enc.EncodeToString(salt), enc.EncodeToString(key)), nil
}

// CheckPassword recomputes the hash with the stored salt and parameters, and compares in
// constant time.
func CheckPassword(pw, stored string) (bool, error) {
  var v int
  var m, t uint32
  var p uint8
  parts := strings.Split(stored, "$")
  if len(parts) != 6 || parts[1] != "argon2id" {
    return false, errors.New("not an argon2id hash")
  }
  if _, err := fmt.Sscanf(parts[2], "v=%d", &v); err != nil {
    return false, fmt.Errorf("read version: %w", err)
  }
  if _, err := fmt.Sscanf(parts[3], "m=%d,t=%d,p=%d", &m, &t, &p); err != nil {
    return false, fmt.Errorf("read parameters: %w", err)
  }
  enc := base64.RawStdEncoding
  salt, err := enc.DecodeString(parts[4])
  if err != nil {
    return false, fmt.Errorf("read salt: %w", err)
  }
  want, err := enc.DecodeString(parts[5])
  if err != nil {
    return false, fmt.Errorf("read hash: %w", err)
  }
  got := argon2.IDKey([]byte(pw), salt, t, m, p, uint32(len(want)))
  return subtle.ConstantTimeCompare(got, want) == 1, nil
}